shamrin

Technical documentation philosophy

A couple of thoughts on technical documentation.

(By "documentation" I mean everything except the source code. Blog posts, API documentation, specifications, code comments, pull request descriptions, commit messages, code review comments, ticket descriptions and comments, videos, pictures, diagrams, presentations etc. etc.)

1. The best documentation is no documentation. For example, prefer refactoring the code to make it self-explanatory if it allows removing the source code comment.

2. By default assume nobody reads documentation. Extra effort is needed to make documentation easy to find and engaging enough so that people would want to read it.

shamrin

/**
 * `n` modulo `d` (because JavaScript `%` remainder operator is useless when `n < 0`)
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Remainder
 * @param {number} n
 * @param {number} d
 */
export function mod(n, d) {
  return ((n % d) + d) % d
}

shamrin

Quick Osmocom OpenBSC installation

Prerequisites

• Ubuntu Trusty (previous LTS and in between versions should work too)
• sudo apt-get install gcc make git autoconf libtool pkg-config build-essential automake libortp-dev python libsqlite3-dev

Installing

shamrin

module First where
import Html exposing (span, text)
main = span [ ] [text "Hello First!"]

shamrin

#!/usr/bin/env fish

set branch (git symbolic-ref -q --short HEAD)
or exit 1

if test $branch = "master"
    echo "error: can't ffmerge master to master, switch to feature branch first"
    exit 2
end

shamrin

module Group where

import List.Extra exposing (span)

countingGroupBy : (a -> b) -> List a -> List (b, Int)
countingGroupBy key xs' =
  let
    eq a b = key a == key b

shamrin

import Html exposing (Html, Attribute, text, div, input, button)
import Html.App exposing (beginnerProgram)
import Html.Attributes exposing (..)
import Html.Events exposing (onInput, onClick)
import String


main =
  beginnerProgram { model = ["", "", ""], view = view, update = update }

shamrin

$ build/lueve -e examples/todomvc-compact.eve
-----ERROR----
DependencyGraph{
  1: #{ } -> #{ variable<object-13-31>, variable<todo>}
    object{binding{ENTITY -> variable<object-13-31>}, binding{tag -> todo-item}, binding{todo -> variable<todo>}, }
  2: #{ }|ANY:#{ variable<todo>} -> #{ variable<todo>}
    expression =(a = variable<todo>, b = variable<todo>)
  3: #{ }|ANY:#{ variable<object-13-67>, variable<todo>} -> #{ variable<todo>, variable<object-13-67>}
    expression =(a = variable<todo>, b = variable<object-13-67>)
  4: #{ } -> #{ variable<object-13-31>, variable<object-13-7>}

shamrin

import Html exposing (Html, Attribute, text, div, input)
import Html.App exposing (beginnerProgram)
import Html.Attributes exposing (..)
import Html.Events exposing (onInput, on)
import String

main =
  beginnerProgram { model = "", view = view, update = update }

shamrin

$ git clone https://github.com/jdubray/sam-safe
$ npm install
npm WARN Invalid name: "sam-safe middleware with blog sample harness"
…
$ # Edit package.json, changing the name field to "sam-safe" in package.json (my npm doesn't like spaces)
$ npm install
$ npm start
> sam-safe@1.0.0 start /Users/user/src/sam-safe
> node server-model.js