Inquiry Question 1: How are large-scale software solutions developed and managed?
Produce technical and user-facing documentation across the software engineering lifecycle, including README files, API documentation, design documents and user manuals
A focused answer to the HSC Software Engineering Module 4 dot point on documentation. README, API docs, design documents, user manuals, the worked example, and the traps markers look for.
Reviewed by: AI editorial process; not yet individually human-reviewed
Have a quick question? Jump to the Q&A page
Jump to a section
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
| 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.
Exam-style practice questions
Practice questions written in the style of NESA exam questions on this dot point, with worked answer explainers. The year tag is the paper they imitate, not the source.
2024 HSC4 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).