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.

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

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

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

‘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

• 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!

Cheers