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

$ 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

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

$ 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

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

module SuperTimer where

import Html exposing (..)
import Html.Events exposing (onClick)
import Time exposing (Time)
import Signal exposing (Address)

type Action = Tick Time | Toggle Bool

type alias Model = { running: Bool, count: Float}

shamrin

$ curl -s https://raw.githubusercontent.com/twitter/twitter-text/master/js/twitter-text.js | uglifyjs | gzip | wc -c
   14988
$ curl -s https://raw.githubusercontent.com/twitter/twitter-text/master/js/twitter-text.js | uglifyjs | wc -c
   40295
$ curl -s https://raw.githubusercontent.com/twitter/twitter-text/master/js/twitter-text.js | gzip | wc -c
   19747
$ curl -s https://raw.githubusercontent.com/twitter/twitter-text/master/js/twitter-text.js | wc -c
   62616