Pre-requisite reading
What sort of documentation is needed?
Effective documentation is essential for any software project to be reproducible, quality assured and transparent. It encompasses both code and the project itself, providing technical details, project management information, records of quality assurance and details of logic, assumptions and decisions made.
We should document:
- a project’s purpose and scope
- how to install or run code or other outputs and their dependencies
- how to use code or other outputs like apps or dashboards
- decisions and changes across a project lifecycle
Why should we document our code and project?
- Understanding: Makes code and project purpose clear, improving transparency.
- Collaboration: Reduces time to become productive for contributors and other users.
- Maintenance: Makes modifying, fixing and refactoring code safer and easier.
- Improved Design: Explaining complex parts often highlights areas for simplification or improvement.
- Accessibility: Makes the project accessible and usable for its intended audience.
- Knowledge: Prevents critical information loss when team members change.
- Standards: Provides a record of how a project has been quality assured and facilitates reproducibility and transparency.
How do we create and maintain quality documentation?
There are considerations that apply to the project itself, or just to code, in addition to more general considerations that apply to both project and code.
- Project-Level:
- The standard files used in code repositories are in the NHSBSA DDaT playbook - similar documentation should exist even for projects where version control is not in use, for example where low-or-no-code tools are used.
- In addition to the standard documentation, a project may also need to include additional documentation.
- Support Information: How to get help, particularly where a project output includes an app-like artifact.
- Design Docs: High-level overview for complex projects.
- Accessibility Statement: If an output is available as a webpage or app, it must have an accessibility statement.
- Code-Level:
- In-Code Comments: Explanations within the code focusing on the why (rationale, complex logic, trade-offs).
- API Documentation: Standardized comments for functions, classes, modules explaining their purpose, parameters, returns, and usage.
- Detailed Explanations: Separate documents or wiki pages for complex algorithms, data structures, or specific modules when needed.
- General
- Start Early & Integrate: Treat documentation as an integral part of the development process, and build updates into your workflow.
- Write Clearly and Concisely: Know your audience for a particular piece of documentation and use straightforward language at the right level.
- Focus on the “Why”: Especially for in-code comments, explain the reasoning behind non-obvious decisions.
- Use Standard Formats & Locations: Employ conventional filenames, formats, and place documentation where users expect it.
- Leverage Tooling
- Use linters and formatters to enforce documentation standards.
- Use tools to generate documentation from code comments.
- Use templates for consistency.
- Maintain Discoverability: Ensure documentation is easy to find and link related documents together.
- Assign Responsibility: Have clear ownership for creating and maintaining different documentation aspects.
How do we define success?
- Documentation enables rapid onboarding of contributors and users.
- Documentation reflects the state of a project, with documentation updates being part of the regular workflow.
- Needed information is easy to locate.
- Documentation covers all aspects adequately for the intended audience, answering reasonable questions.
Lookout for:
- Critical friends and other peer-reviewers should consider and feedback on documentation, in addition to code and outputs.
- Creating and updating documentation is often overlooked during project planning: be sure to allocate sufficient time for documentation in your estimates.
- Include documentation in retrospective discussions to ensure it’s improving and evolving in line with the rest of the analysis.