How to write technical documentation

Writing docs

We use the most popular static site generator Jekyll to generate this website. Hosting is done automatically by Cloudflare pages.

Theme

Chirpy is a Jekyll theme which looks good and also supports dark mode.

Jekyll and Chirpy support asciidoc via the asciidoctor plugin but currently we only use markdown. See section Problems.

Installation

• Install Jekyll
• Clone the repository tech-docs-eb
• Run bundle install
• If you want to test it out locally, run jekyll serve

New docs

• Write all posts in the _posts/ folder
• File names: YYYY-MM-DD-my_new_post.md
• In case you are writing an ADR (Architecture Decision Records), file name should be YYYY-MM-DD-adr_my_new_adr.md
• For faq, name the file to YYYY-MM-DD-faq_my_new_faq.md
• Refer to Chirpy documentation: Getting started and writing a new post for tips to structure your document

Diagrams

Mermaid is included by default for creating diagrams. Thereby, it is easy to maintain the diagrams as documentation.

Example

When you write the following class diagram encapsulated in mermaid... blocks:

  classDiagram
      Animal <|-- Duck
      Animal <|-- Fish
      Animal <|-- Zebra
      Animal : +int age
      Animal : +String gender
      Animal: +isMammal()
      Animal: +mate()
      class Duck{
          +String beakColor
          +swim()
          +quack()
      }
      class Fish{
          -int sizeInFeet
          -canEat()
      }
      class Zebra{
          +bool is_wild
          +run()
      }

the following diagram will be created:

  classDiagram
      Animal <|-- Duck
      Animal <|-- Fish
      Animal <|-- Zebra
      Animal : +int age
      Animal : +String gender
      Animal: +isMammal()
      Animal: +mate()
      class Duck{
          +String beakColor
          +swim()
          +quack()
      }
      class Fish{
          -int sizeInFeet
          -canEat()
      }
      class Zebra{
          +bool is_wild
          +run()
      }

References

• Markdown cheat sheet

Problems

Incremental builds on Cloudflare are not yet implemented and tested. When you make a small change to the documentation, the entire website is rebuilt. This is sub-optimal.

I wanted to use asciidoc, but there was an issue with the generated HTML. Some features of the chirpy theme are not displayed properly. This can be resolved, to be done when time permits.

Test line.