Part 2: The Goodies of Technical Documentation
This is sooo good!
In case you missed Part 1 be sure to check that out. It covers the concepts of technical documentation. Part 2 will go into the deliverables for the documentation you are creating.
Deliverables : Requirements
Unitary (Cohesive) — Address only one thing
Complete — Fully state in one place, with no missing information
Consistent — Do not contradict any other requirement; fully consistent with all authoritative external documentation
Atomic — Do not contain conjunctions
‘ Validates fields A and B’ becomes = 1. Validate field A 2. Validate field B
Traceable — Meet all or part of a business need as stated by stakeholders and is authoritatively documented
Current — Do not use data made obsolete by the passage of time
Unambiguous — Concisely state without use of jargon, acronyms or esoteric verbiage; expresses objective facts; subject to one interpretation
Specify Importance — Specify a level of importance (defined by stakeholders, time or budget)
Verifiable — Determine implementation through inspection, demonstration, test or analysis
Deliverables: Design / Architecture
‘If I’m writing documentation, I am not writing code”
“Nobody reads documentation”
Software Design Document (SDD)
A written description of a software product that gives a development team overall guidance to the architecture of the software project.
Manager / Stakeholders
- Establish clear design goals
- Show that you understand the requirements and have a plan to meet them
- Establish common understating and terminology
- Help with time and resource estimation
- Communicate the design to the team
- Validate design decisions
- Ensure the approach works with what others are doing
- Onboard documentation for new team members and / or successors
- Use historical references / starting point for future projects
- Consider regulatory reasons (getting audited?)
Deliverables: Code Documentation
No, I’m serious, help
This is probably how most developers feel when asked to document their code or development process. Trust me you are not alone. But once you do it, and follow these easy steps, you won’t have to explain to everyone, a million times.
How NOT to use comments
- To state something obvious or redundant
- To explain poorly-written or poorly-designed code
- To sort of delete code //comment it out
How TO use comments
- Utilize high level comments
- Use TODO, HACK and UNDONE
Instructions for how to effectively use APIs of hardware or software
- Newbie developers
- Developers needing to debug
- Business people or developers evaluating the API
What should be included?
- Reference documents
- Overview and concepts
- Tutorials and training
- Installation / getting started / troubleshooting
- SDK tool documents
- License information
Deliverables: End-User Documentation
‘But if it’s intuitive, we don’t need documentation, right?’
Three types of End-User Documentation
User Guides — Help user understand and use system
- What does it do?
- What are the major features?
- Why should I use it?
- How should I use it?
- How does it fit with the other systems I am using?
Quick Reference Guides
- Reference tables
- Graphics / infographics
Release Notes — Document the difference between two versions of the same software (e.g.: v1 and v2)
I hope these tips have given you ideas and strategies to successfully write some kick butt technical documentation. Make sure to bookmark Part1 too!