Documentation practices explained: HSC Software Engineering Module 4
“Produce technical and user-facing documentation across the software engineering lifecycle, including README files, API documentation, design documents and user manuals”
Technical documentation (README, API reference, design documents, runbooks, architecture diagrams) serves developers. User documentation (user manuals, FAQ, release notes, in-app help) serves end users. Treat documentation as code: in source control, reviewed alongside the code, kept up to date. Default to no comments inside code; explain non-obvious WHY when needed.
Jump to a section
Think of a software project like a rental house being handed to a new tenant. The tenant needs an instruction sheet for the house itself, where the fuse box is, how the hot water works, what day the bins go out, that's technical documentation for developers. But the house also needs a welcome guide for guests staying there, how to work the TV remote, the wifi password, that's user documentation for end users. If the instruction sheet was written the day the house was built and never updated after the hot water system was replaced, it becomes actively dangerous rather than just outdated, which is exactly why teams write documentation alongside the code and update it in the same pull request, not months later from memory.
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.
Before writing any document, ask one question: "who reads this, and what do they need to be able to DO afterwards?" A developer needs to be able to run, extend or fix the system. An end user needs to be able to complete a task in the product. If a document tries to serve both audiences at once (a README full of screenshots for customers; a user manual full of API parameter tables) it usually serves neither well. Split it into two documents instead.
Technical documentation
| Document | Audience | Purpose |
|---|---|---|
| README | Developers landing on the repo | How to set up, run, test, contribute |
| API reference | Developers integrating | Every endpoint, request and response |
| Design document | Maintainers and reviewers | The architecture and why it is this way |
| Code comments | Future code readers | Why this code does what it does (when non-obvious) |
| Architecture diagram | Visual learners and reviewers | High-level system shape |
| Runbook | On-call engineers | What to do when something breaks |
| Migration guide | Users upgrading versions | How to move from version N to N+1 |
| Changelog | Users updating | What changed in each release |
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. The diagram below shows where documentation sits in a healthy pull-request pipeline, and where it is skipped when documentation quietly rots.
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.
A team has finished its Major Project. List the documentation they should produce, the audience for each, and which is essential for marking.
- README.md (developer audience): how to set up and run the project locally. Essential for markers who will run the code.
- User manual (end-user audience): how to use the app, with screenshots. Essential for showing the product works.
- Architecture diagram (maintainer audience): the three-tier setup with components labelled. Required by most rubrics.
- API documentation (integrator audience): if the project exposes an API. Use auto-generated docs.
- Project journal / design log (assessor audience): decisions made, alternatives considered, problems solved. Required by NESA for Major Projects.
- Test plan and test results (assessor audience): what was tested and the outcomes.
The journal/design log is the highest-value document for marking. It demonstrates engineering judgement and project management, which are explicitly assessed.
Marker's note: full marks require BOTH the correct audience for each document (developer, end user, maintainer, integrator, assessor) and a clear statement of which document carries the most marking weight, with a reason grounded in what NESA explicitly assesses (engineering judgement and process, not just the finished code).
If a question says "distinguish" or "compare", markers want audience-based reasoning (who reads it, what they need to do), not just a list of document names. If a question gives a scenario ("a team is six weeks from submission" or "a pull request changes an endpoint"), anchor your answer in specifics from that scenario rather than reciting the general theory, then finish by naming the concrete document and process fix the scenario calls for.
- Writing documentation as an afterthought
- Documentation written in the last week of the project is incomplete and rushed. Update it as you go.
- Auto-generated dump masquerading as documentation
- A long file of class signatures is not documentation. Real documentation explains the why and shows examples.
- Code comments restating the code
- A comment saying "increment counter" next to a one-line counter increment is noise. Comments are for the WHY.
- Forgetting the user audience
- Technical documentation is necessary but not sufficient. End users need their own documentation.
- Documentation in a private wiki
- If it is not in the repo, it goes out of date. Co-locate documentation with the code it describes.
Exam-style questions
Questions in the style of NESA exam questions on this dot point, each with a worked answer. They are written by ExamExplained unless tagged "Past paper"; the year shows the paper a question is modelled on.
Practice4 marksDistinguish between technical documentation and user documentation. Give a specific example of each in a software project.Show worked answer →
Technical documentation is for developers who maintain or integrate with the software. It describes how the system is built, the design decisions, and how to work with the code. Examples: a README explaining how to set up the project locally, an API reference describing every endpoint with sample requests, a design document explaining the architecture and why certain choices were made.
User documentation is for end users. It explains how to use the software to accomplish goals. Examples: a user manual covering the main workflows, an in-app help system, frequently-asked-questions pages, video tutorials, release notes summarising what is new.
Specific examples in a project:
Technical: a README.md at the root of the GitHub repo with sections for prerequisites (Python 3.11, PostgreSQL 15), local setup (pip install -r requirements.txt; flask run), running tests (pytest), deployment (docker compose up), and architectural overview (a diagram of the three-tier setup).
User: a help page on the website explaining how to register, log in, reset a password, create a study session, and export data. Written without technical jargon, with screenshots.
Markers reward both definitions, the audience distinction (developers vs end users), and concrete examples (not just "manual" and "code").
Practice questions
Original practice questions graded from foundation to exam level, each with a full worked solution. Try them before revealing the solution.
foundation3 marksList three essential sections of a project README and state, in one sentence each, what a developer expects to find in each section.Show worked solution →
Any three of the following earn marks, one mark per correctly described section (maximum 3):
- Prerequisites: the software, language version and services a developer must already have installed (for example Python 3.11, PostgreSQL 15) before setup will work.
- Setup: the exact commands to clone the repository, install dependencies and configure local environment variables.
- Running: the command(s) to start the application locally, and the URL or port to visit.
- Tests: the command to run the automated test suite, so a change can be verified before committing.
- Deployment: how the project is shipped to production, or a link to a deployment runbook.
Marking criteria: 1 mark per section named AND correctly described (a section name alone with no description earns no mark).
foundation3 marksExplain the difference between technical documentation and user documentation, giving one example of each that is NOT a README or a user manual.Show worked solution →
Technical documentation is written for developers: it describes how the system is built and why, so it can be maintained, extended or integrated with. Example other than a README: an API reference listing every endpoint, its parameters and example responses.
User documentation is written for end users: it explains how to use the software to achieve a goal, without assuming any coding knowledge. Example other than a user manual: release notes describing, in plain language, what changed in the latest version and what a user needs to do differently.
Marking criteria: 1 mark for the audience-based distinction (developers vs end users), 1 mark for a valid technical example other than README, 1 mark for a valid user example other than a user manual.
core4 marksSTIMULUS. A pull request changes the `/api/orders` endpoint to require a new `customerId` field in the request body, but the PR contains no changes to any documentation file. Two weeks later, an external developer integrating with the API reports that their requests are failing with no clear reason why. (a) Identify the documentation practice that was broken. (b) Recommend one process change that would have prevented this.Show worked solution →
(a) What broke. The team violated 'documentation as code': a change to observable behaviour (a new required field) was merged without an accompanying update to the API documentation. The API reference now describes an endpoint that no longer matches reality, so the external developer has no way to discover the new requirement.
(b) Process fix. Require that PRs changing an endpoint's request or response shape update the API documentation (ideally auto-generated from the code, e.g. via OpenAPI annotations) in the SAME pull request, and have reviewers reject PRs that change API behaviour without a matching documentation diff.
Marking criteria: 1 mark for identifying the missing/stale API documentation as the root cause, 1 mark for linking it to the 'documentation as code' principle, 1 mark for a concrete process fix (same-PR requirement or reviewer gate), 1 mark for connecting the fix to preventing exactly this failure mode (external integrators breaking silently).
core4 marksA maintainer says: 'We don't need a design document, the code review will catch any problems.' Explain why this reasoning is flawed for a non-trivial architectural change.Show worked solution →
A design document is reviewed BEFORE any code is written, while the approach is still cheap to change. A code review happens AFTER the implementation exists, so by the time problems are raised, the author has already invested significant time in one specific approach and reviewers can only suggest fixes within that approach rather than questioning it wholesale.
A design document also records alternatives considered and non-goals, which a code review of the final implementation cannot recover: reviewers reading only the code have no visibility into what else was tried, or deliberately excluded, and why.
For small, low-risk changes this overhead is not worth it, but for changes with real architectural consequences (new data model, new service boundary, a breaking API change), skipping the design document risks a costly rewrite discovered only at code-review time.
Marking criteria: 1 mark for identifying the timing difference (before vs after implementation), 1 mark for explaining the cost-of-change consequence, 1 mark for noting that alternatives/non-goals are lost without a design document, 1 mark for scoping the argument to non-trivial/architectural changes rather than all changes.
core5 marksSTIMULUS. An API reference entry reads only: 'POST /login - logs a user in.' Rewrite this into a complete API documentation entry, inventing plausible but realistic parameters, an example request and response, and status codes.Show worked solution →
A complete entry needs all the standard fields. A plausible model answer:
POST /login
Authenticates a user and returns a session token.
Parameters (body, JSON):
email(string, required): the user's registered email address.password(string, required): the user's plaintext password (sent over HTTPS only).
Example request:
POST /login
{ "email": "jane@example.com", "password": "hunter2" }
Example response (200):
{ "token": "eyJhbGciOi...", "expiresIn": 3600 }
Status codes: 200 success, 400 missing or malformed field, 401 incorrect email or password, 429 too many attempts (rate limited).
Authentication: none required to call this endpoint (it is how a client obtains authentication).
Marking criteria: 1 mark for correctly typed parameters, 1 mark for a realistic example request, 1 mark for a realistic example response including a token/session concept, 1 mark for at least three distinct, correctly meaning status codes, 1 mark for correctly stating the authentication requirement (none, since this endpoint issues auth).
exam6 marksEvaluate the claim that automatically generated API documentation (for example from OpenAPI annotations) is sufficient documentation for a software project, on its own.Show worked solution →
This is a 6-mark EVALUATE: markers want a judgement supported by both sides of the argument, not a one-sided description.
- Case for sufficiency
- Auto-generated API documentation stays accurate almost by construction: because it is derived from the code (parameter types, routes, response shapes), it cannot drift the way a hand-written document can. It is also fast to produce and covers every endpoint uniformly, which is valuable for large APIs where hand-written docs would lag behind rapid change.
- Case against sufficiency
- Auto-generated documentation only captures what the code's structure can express: parameter names and types, not WHY an endpoint exists, what business rule governs a field's validity, or how endpoints should be combined to complete a real workflow. It also documents nothing for end users of the finished product; a user manual, FAQ or release notes cannot be auto-generated from function signatures because they are about the human task, not the code shape. Design documents and architecture diagrams (the WHY and the shape of the whole system) are similarly outside what code annotations can produce.
- Judgement
- Auto-generated API documentation is a necessary and highly effective component of TECHNICAL documentation for keeping the reference accurate, but it is not sufficient on its own: it must be supplemented with hand-written context (a README's setup and architecture sections, a design document's rationale) for developers, and with separate USER documentation entirely, since auto-generation cannot address the end-user audience at all.
Marking criteria: 1 mark for a clear thesis/judgement, 2 marks for the case for sufficiency (accuracy from code, coverage, speed), 2 marks for the case against (missing rationale/business rules/workflow context, and the entirely separate user-documentation need), 1 mark for a coherent concluding judgement that weighs both sides rather than restating them.
exam7 marksA four-person Major Project team (three-tier web application: React front end, Flask API, PostgreSQL database) is six weeks from submission and has produced almost no documentation so far. Design a documentation plan for the remaining six weeks: name each document they should produce, its audience, and one concrete step to stop it going stale before submission.Show worked solution →
A strong 7-mark plan names multiple documents, matches each to its correct audience, and gives a genuinely actionable anti-staleness step (not just 'keep it updated').
README.md (audience: the marker running the code). Write incrementally as each part of the stack stabilises; freeze and verify it works from a completely clean checkout in the final week.
API reference (audience: the front-end developer integrating with the Flask API, and the marker). Generate it from code using a tool such as Flask-Swagger/OpenAPI annotations so it cannot drift from the actual routes as the API changes over the six weeks.
Architecture diagram (audience: the marker/reviewer). Draw the three tiers (React, Flask, PostgreSQL) with the data flow between them once the architecture is stable, roughly week 3 to 4, then revisit once in week 6.
User manual (audience: end users, and the marker assessing usability). Write it last, once the UI is stable, with real screenshots from the built app rather than mockups.
Project journal / design log (audience: the marker; NESA-required). Do NOT write this retrospectively: require every team member to add a short entry after each significant decision or problem solved, in the same week it happens, so the record is accurate rather than reconstructed from memory in week 6.
Anti-staleness step: add a documentation checklist item to every pull request template so no code change affecting setup, an endpoint or the UI is merged without its matching documentation section being touched in the same PR.
Marking criteria: 1 mark each for identifying README, API reference, architecture diagram, user manual and journal/design log (5 marks total, must include the audience for each to gain the mark), 1 mark for a genuinely concrete anti-staleness mechanism (not a vague 'update regularly'), 1 mark for sequencing that reflects when each document can realistically be written (e.g. user manual last, journal continuously).