ZSI / Documentation

Reading

An investment in knowledge always pays the best interest.

— Benjamin Franklin

Invest Regularly in Your Knowledge Portfolio

Make learning a habit.

— The Pragmatic Programmer

What to read?

Books

• The Pragmatic Programmer by David Thomas, Andrew Hunt
• Clean Code by Robert C. Martin
• The Art of Unix Programming by Eric S. Raymond

Blogs of professionals

• Daniel Lemire's blog
• Clean Coder Blog
• Martin Fowler
• UX & Usability Articles from Nielsen Norman Group

Official documentation

• Usually the best source for specific technology

Not only technical

• Discover different areas
• Read classics

Writing

English is Just Another Programming Language

Treat English as Just Another Programming Language. Write documents as you would write code: honor the DRY principle, ETC, automation, and so on.

— The Pragmatic Programmer

Writing

• audience
• what you want to say?
• style

Example

Pyramid principle

1. Key message
2. Supporting arguments
3. Supporting data or facts, context

Documentation

1. Tutorial
2. Reference manual

Example: Django documentation, manual pages

How to write documentation?

Tools

• wiki
• web page generators

Markdown

Markdown

• lightweight markup language
• translated to HTML or other formats
  • e.g. MkDocs

# Header

Paragraph of some **important** text, `code`
and [a link](http://examle.com)

- A list
- with
- multiple
- items.

Documentation comments

• tools for building documentation from comments
  • Doxygen
  • Javadoc
  • Sphinx

Architecture Decision Records

• important architecture decisions
• keep in source control
• structure
  1. Context
  2. Decision
  3. Status
  4. Consequences

Suggested by

• Microsoft: Microsoft Azure Well-Architected Framework
• RedHat Why you should be using architecture decision records to document your project
• Spotify: When Should I Write an Architecture Decision Record
• and others

Example

• IT4KT Builder