Technical writing

A Practical approach

Write what you want to say, then rewrite the way you wish to say it, e.g brain-dump thoughts at first without concern for the prose, refactor to make thoughts intelligable and easily consumable.

The hardest part of writing can be getting over the blank page.

A focus on capturing thoughts first ... a wider or deeper coverage of what is to be said. Once extensive thoughs are captured, apply refinement to how thoughts are express (without risk of loosing thoughts).

Website generators

Static web sites are fast to serve and low maintenance, providing an excellent approach to serving up technical documentation.

Using Markdown or Asciidoc minimises the learning curve for creating documentation, allowing thoughts to be captured quickly without distracting concerns on visual presentation.

Clojure tech docs

cljdoc

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Tips

• learn English grammar
• avoid English pronouns, pronouns are often an indicator of verbosity