Back to the full dot-point answer
NSWSoftware EngineeringQuick questions
Module 4: Software Engineering Project
Quick questions on Documentation practices explained: HSC Software Engineering Module 4
12short Q&A pairs drawn directly from our worked dot-point answer. For full context and worked exam questions, read the parent dot-point page.
What is technical vs user documentation?Show answer
Two broad categories defined by audience:
What is a good README?Show answer
The README is the front door of the project. A minimum:
What is aPI documentation?Show answer
Tools that generate API docs from code: OpenAPI/Swagger, Sphinx, JSDoc, FastAPI's auto-generated docs.
What is design documents?Show answer
For non-trivial changes, write a design document before coding. Standard sections:
What is code comments?Show answer
Default to writing no comments. A well-named function, variable and class makes the code self-explanatory.
What is user documentation?Show answer
For end users (not developers):
What is documentation as code?Show answer
Treat documentation like code: in source control, reviewed in pull requests, kept up to date with the code it describes. Tools:
What is the maintenance problem?Show answer
The fastest way to lose user trust is documentation that is out of date. Solutions:
What is auto-generated dump masquerading as documentation?Show answer
A long file of class signatures is not documentation. Real documentation explains the why and shows examples.
What is code comments restating the code?Show answer
A comment saying "increment counter" next to a one-line counter increment is noise. Comments are for the WHY.
What is forgetting the user audience?Show answer
Technical documentation is necessary but not sufficient. End users need their own documentation.
What is documentation in a private wiki?Show answer
If it is not in the repo, it goes out of date. Co-locate documentation with the code it describes. :::