Documentation/Technical documentation templates and suggestions

Overview
This page provides some tips for designing and writing in specific types (genres) of technical documentation for software development. Different kinds of technical documentation often have specific features, which set them apart from other genres. A number of genres or document types are used frequently by technical documentarians to communicate information to audiences.

Each genre may have particular features documentarians include or audiences expect. When documentarians choose genres that audiences are familiar with and expect, this can help the audience understand more easily.

When you know your audience and what kind of information you would like to convey, it can be helpful to decide on a specific genre or document type before you start writing. When you know what kind of document you are creating, you may find it easier to structure the document and format your information.

What is a genre?
Genre is one way to classify the kind of writing you are doing. Genre can help determine the structure or form your writing will take. Genres can usually be identified by sets of expectations and conventions. Something written in a particular genre will typically share the same or similar features of other pieces of writing in a particular genre -- though they may not share all of the same expectations and conventions.

Some examples of genres

 * FAQ
 * Walkthrough
 * Tutorial
 * How-to
 * Quickstart guide (QSG)
 * User guide, reference guide, technical manual
 * README
 * Glossary
 * API Documentation, SDK (Software Development Kit), Code
 * Troubleshooting
 * Release notes
 * White paper
 * Datasheet
 * Technical specification
 * Blog post
 * Abstract
 * Position paper
 * Tickets (task, bugs, features request, etc)
 * Conference presentations and panels
 * ...and more

FAQ
An FAQ is a list of frequently asked questions (FAQs) and answers, often seen on technical support websites.

Tips


 * The Facts About FAQS presentation. Write the Docs, Portland 2018

Examples


 * ORES FAQ

Walkthroughs, how-tos, and tutorials
This genre of documentation helps guide audiences through a specific process step by step.

Tips
 * Use code examples and screenshots to help orient users
 * For web-based tutorials, use a progress tracker

Examples
 * GitHub tutorial
 * My First Flask OATH Tool

Quickstart guide (QSG)
A quickstart guide is a short tutorial designed to get users up and running with a software application or tool.

Tips
 * List all requirements, steps, and terminal commands
 * To keep the quickstart guide brief, use links to point users to where they can find more information

Examples
 * Jekyll quickstart
 * CockroachDB Quickstart

User guides, reference guides, and technical manuals
Tips Examples
 * https://www.prismnet.com/~hcexres/textbook/user_guides.html User guide information

README
A README is a plain text file that describes how to install and use software.

Tips

Examples


 * Feedmereadmes
 * https://github.com/curl/curl/blob/master/README CURL README

Glossary
Tips

Examples

API Documentation, SDK (Software Development Kit), Code
Tips

Examples

More information


 * API Documentation Writing
 * Documenting APIs: A guide for technical writers

Troubleshooting
Tips

Examples

Release notes
Release notes describe new features and bug fixes for software.

Tips
 * Write concisely and use bullet points
 * Consider writing different versions of release notes per operating system; some features on one system may not be applicable to another

Examples
 * Slack Release Notes

White paper
Tips

Examples

Datasheet
A datasheet is a document that describes features and technical specifications of a product.

Tips
 * Datasheets should be brief; try limiting the document to one or two pages
 * Include wiring diagrams, graphics, and illustrations

Examples


 * Access control panel datasheet

Technical specification
Tips

Examples

Blog post
Tips

Examples

Abstract
Tips

Examples

Position paper
Tips

Examples

Tickets (task, bugs, features request, etc)
Tips

Examples

Conference presentations and panels
Tips

Examples

Additional information

 * Technical Communication
 * Software Documentation
 * Golden Rule of Code Documentation