Table of Contents


If you want to be a writer, you must do two things above all others: read a lot and write a lot. There's no way around these two things that I'm aware of, no shortcut.

(Stephen King)

Seven Rules for good documentation

  1. Write documentation from the point of view of the reader, not the writer.
  2. Avoid unnecessary repetition.
  3. Avoid ambiguity. Always explain your notation.
  4. Use a standard organization.
  5. Record rationale.
  6. Keep documentation current but not too current.
  7. Review documentation for fitness of purpose.

Quoted from the book "Documenting Software Architectures" by szoerner.

User documentation

Guided tour

Short manual



  • Creation date
  • Contact information
  • Software name, version, pricing
  • Brief description of the software
  • Installation requirements
  • Copyright and license info


Technical documentation


With a comprehensive, well-written README any developer should be able to hop on to your project and begin hacking away within 10 minutes. – Jordan Maguire

  • Brief into into the project: Project name, purpose, online tools, contact information
  • Getting started quickly: How to get the application installed and ready for development?
  • Testing: How to run the test suite(s)?
  • Deployment process: How to access the involved environments and servers?

Read more:



  • Context diagram

    Example Context diagram

    • shows the big picture
    • own system block in the middle
    • users
    • other systems
  • Container diagram

    Example Container Diagram

    • high-level view on architecture, technical choices and responsibility distribution
    • stores of code or data
    • e.g. web server, mobile app, db, file sytem
  • Components diagram

    Example Components diagram

    • decomposition of individual containers
    • major logical components
    • their interaction
    • e.g. services, modules, subsystems, layers, workflows
  • Class diagram
    • optional
    • some high level UML class diagrams
    • sketches rather than comprehensive models