Part 2: The Goodies of Technical Documentation

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


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


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


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!


Post a Comment

#Follow on Instagram