Skip to content

Technical writingλ︎

Tools and writing techniques to deliver high quality documentation and articles on the topic of software development.

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 intelligible 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 thoughts are captured, apply refinement to how thoughts are express (without risk of loosing thoughts).

Tool supportλ︎

The Proselint tool improves the use of English, distilling decades of experience in writing modern English

Using Proselint within an editor provides feedback to improve writing as its written.

Add a $XDG_CONFIG_HOME/proselint/config.json file if there are checks that are not required or experiencing warnings that are not relevant, e.g. Python markdown syntax use for Zensical websites used to create the Practicalli content.

Practicalli dotfiles example Proselint config

A proselint/config.json configuration was created in practicalli/dotfiles and a symbolic link to the proselink directory created in

{
  "checks": {
    "annotations": false,
    "lexical_illusions": false,
    "typography.symbols.curly_quotes": false,
    "typography.symbols.ellipsis": false,
    "typography.punctuation.hyperbole": false
  }
}

The reason for disabling these checks:

  • annotations warns about TODO: and similar notes in the text
  • lexical_illusions warn on repeated words (trips up on log and shell output examples)
  • typography.symbols.curly_quotes warns double quotes in text should be curly - complains about code examples.
  • typography.punctuation.hyperbole false warning for annotation syntax
  • typography.symbols.ellipsis warns on `...

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 is a website that hosts documents for Clojure libraries and tools. Libraries pushed to Clojars should have their docs available to build on cljdoc.org.

cljdoc

Tipsλ︎