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
 * User guide, Reference guide, Technical Manual
 * Quick start guide (QSG)
 * README
 * Glossary
 * API Documentation, SDK (Software Development Kit), Code
 * Troubleshooting
 * Release notes
 * White paper
 * Data sheet
 * Technical specification
 * Blog post
 * Abstract
 * Position paper
 * Tickets (task, bugs, features request, etc)
 * Preparing for conference presentations and panels
 * ...And More

FAQ
Tips


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

Examples


 * ORES FAQ

Walkthroughs, how-tos, and tutorials
Walkthroughs help guide audiences through a specific process step by step. They often utilize code examples and screenshots to help orient users. They are also often

Tips

Examples


 * My First Flask OATH Tool

User guides Reference guides Technical Manual
Tips Examples
 * User guide information

Quickstart_guide Quick start guide (QSG)
Tips

Examples

README
Tips

Examples


 * Feedmereadmes

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
Tips

Examples

White paper
Tips

Examples

Data sheet
Tips

Examples

Technical specification
Tips

Examples

Blog post
Tips

Examples

Abstract
Tips

Examples

Position paper
Tips

Examples


 * Tickets (task, bugs, features request, etc)
 * Preparing for conference presentations and panels

Additional information

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