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)

General guidelines

User documentation


  • Help messages, to understand how the software is working
  • Useful error messages

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?
  • Contact information

Read more:

Source code

  • Guide to known issues
  • Public API description

Operations playbooks

  • How to troubleshoot the system
  • Doing backups etc.


  • system overview: Purpose, Which problem does it solve an how?
  • Tech stack
  • Project structure
  • System components


  • 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