Documentation

Table of Contents

Introduction

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)

  • Provide the information relevant for your targeted reader.
  • Write an outline for each section.
  • Use images and concept maps for support of the description.
  • Use practical examples to avoid grey theory.

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

Handbook

README

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

(see wikihow.com)

Technical documentation

README

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)

  • General information: Project name, purpose, online tools, contact information
  • Getting started: 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:

Architecture

c4

  • 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

arc42

API

Examples are the most important building blocks of your documentation.

(@craftsmancoding)

GitHubImpressum