Writing is an essential skill for software developers.
Software documentation should cover the development and engineering decisions, not the code. It should explain why and how it was built and is maintained. An ideal to strive for is making it possible to recreate the system from scratch, without access to the code, should it be necessary.
Technical documentation for any software system should include:
- A logical model of the domain
- logical architecture schema
- physical architecture schema
Over the course of a project or within in an ongoing capability, start and keep a log of technical decisions, using a consistent format, such as Lightweight Architectural Decision Records or Technical Memo.
Bug-tracking system tickets also record history for technical decisions, serving as both reference and explanation.
Good documentation will focus on four needs, and additional types can fill further needs. Additional tips for design docs and technical specs.
A technical design doc is the third of three documents produced in a typical development process:
- Product Requirements Document
- Technical Requirements Document
- Technical Design Document
- between 1 and 10 pages
- provide context
It is an aspect of software technical documentation, not the only technical document.
Include a list of people and their roles. This could include their official titles.
Explain the context: what problem are we trying to solve? Relate it to overall product,technical, and corporate strategies.
Have a “won’t do” section. Be clear about what you’re leaving out and why.
Discuss the existing solution (if any), how it works, and why it is how it is. Apply a variety of perspectives in describing the existing and proposed solutions.
In addition to describing the solution, discuss the alternatives considered and why they were rejected.
Be sure to lay out a plan for testing, monitoring, and alerting.
Discuss the impact of the solution: costs, on-call & dev-ops, support burden, system & security concerns.
Include charts and diagrams (or even videos & animations, if possible), to help explain things for different learning styles.
Development of a good technical specification involves review and refinement process.