Produce technical and user-facing documentation across the software engineering lifecycle, including README files, API documentation, design documents and user manuals

What this dot point is asking

NESA wants you to identify the different kinds of documentation a software project needs, who each is for, and what good documentation looks like.

The answer

Technical vs user documentation

Two broad categories defined by audience:

• Technical: for developers (maintainers, integrators, new joiners).
• User: for end users of the software.

Technical documentation

A good README

The README is the front door of the project. A minimum:

# Project name

One-line description.

## Prerequisites

- Python 3.11 or newer
- PostgreSQL 15
- Node 20 (for the front-end build)

## Setup

git clone https://github.com/team/project.git
cd project
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # fill in your local values
psql < schema.sql

## Running

flask run
# in another terminal:
npm run dev

Visit http://localhost:5000.

## Tests

pytest
npm test

## Deployment

See deploy/README.md for the deployment runbook.

## Architecture

[diagram or link]

## Contributing

See CONTRIBUTING.md.

A new developer should be able to run the project locally within 30 minutes from the README alone.

API documentation

For each endpoint:

• HTTP method and path.
• Description.
• Parameters (path, query, body) with types and constraints.
• Example request.
• Example response.
• Status codes.
• Authentication requirements.

Tools that generate API docs from code: OpenAPI/Swagger, Sphinx, JSDoc, FastAPI's auto-generated docs.

Design documents

For non-trivial changes, write a design document before coding. Standard sections:

• Context: what is the problem.
• Goals: what we want to achieve.
• Non-goals: what we explicitly are not doing.
• Design: the proposed solution.
• Alternatives considered: what else we thought about and why we rejected it.
• Implications: cost, risk, dependencies.
• Roll-out plan: how we ship it safely.

Reviewed before implementation starts. Saves more time than it costs.

Code comments

Default to writing no comments. A well-named function, variable and class makes the code self-explanatory.

Write a comment when:

• A future reader will find the code surprising and benefit from the why.
• There is a subtle invariant or hidden constraint.
• A workaround exists for a specific bug.

Do not comment what the code does ("increment counter"). Do not reference the current task or callers.

# Good:
# Use UTC explicitly. Australia/Sydney's daylight-saving transitions
# corrupt the timestamps in our nightly export when running across midnight.
ts = datetime.now(timezone.utc)

# Bad:
# Get the time and assign it to ts
ts = datetime.now(timezone.utc)

User documentation

For end users (not developers):

• User manual or help centre: how to do the main tasks.
• Tutorials: step-by-step for common goals.
• FAQ: common questions answered.
• Video walk-throughs for visual learners.
• Release notes: what changed and what users need to do.
• In-app help: tooltips and inline guidance.

Style: plain language, short sentences, screenshots, examples.

Documentation as code

Treat documentation like code: in source control, reviewed in pull requests, kept up to date with the code it describes. Tools:

• Markdown for most documentation.
• MkDocs, Docusaurus, VuePress for static sites.
• OpenAPI for API specs.
• Read the Docs for hosted documentation.

The maintenance problem

The fastest way to lose user trust is documentation that is out of date. Solutions:

• Generate API docs from the code automatically.
• Include the documentation update in the same pull request as the code change. Reviewers should reject PRs without documentation updates.
• Add a "last reviewed" date to long-lived documents and revisit periodically.