Part 2: The Goodies of Technical Documentation

 

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

 

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.

WHY?

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

 

Fellow Developers

• 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

 

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

 

API Documentation

Instructions for how to effectively use APIs of hardware or software

 

API audience:

• 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

 

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

• Diagrams
• Reference tables
• Steps
• 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!