User:Pavithraes/Sandbox/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.

A number of genres or document types are used frequently by technical documentarians to communicate information to audiences. Different genres of technical documentation often have specific features that documentarians include and audiences expect.

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. After selecting the type 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.

Tips and examples
{| class="wikitable" ! GENRE !! DETAILS !! TIPS AND RESOURCES !! EXAMPLES



FAQ

 * An FAQ is a list of frequently asked questions (FAQs) and answers, often seen on technical support websites.
 * The Facts About FAQs presentation. Write the Docs, Portland 2018
 * ORES FAQ
 * ORES FAQ
 * ORES FAQ



Walkthroughs, how-tos, and tutorials

 * This genre of documentation helps guide audiences through a specific process step by step.
 * Use code examples and screenshots to help orient users.
 * For web-based tutorials, use a progress tracker. Enable quick wins to make the reader feel encouraged.
 * GitHub tutorial
 * My First Flask OATH Tool
 * Wikipedia:Tutorial
 * My First Flask OATH Tool
 * Wikipedia:Tutorial



Quickstart guide (QSG)

 * A quickstart guide is a short tutorial designed to get users up and running with a software application or tool.
 * 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.
 * Jekyll quickstart
 * CockroachDB Quickstart
 * Jekyll quickstart
 * CockroachDB Quickstart



User guides, reference guides, and technical manuals

 * A task-oriented guide that contains installation and usage instructions for the end-users of a software/product.
 * User guide information
 * Youtube user guide
 * Phabricator user guide
 * Youtube user guide
 * Phabricator user guide



README

 * A README is a plain text file that describes the directories and files in the software code. It also contains information on how to install and use the software.
 * README tips
 * Feedmereadmes
 * CURL README
 * Feedmereadmes
 * CURL README

==== API Documentation, SDK (Software Development Kit) Documentation ==== API and SDK aren't synonymous even though they are frequently used together. Their documentation is developer oriented with usage information.
 * API Documentation Writing
 * Documenting APIs: A guide for technical writers
 * Google Cloud SDK
 * Heroku API reference
 * Google Cloud SDK
 * Heroku API reference

Troubleshooting

 * A troubleshooting document contains solutions for the possible issues that a user might encounter while installing, configuring or using a product/software.
 * Use self-explanatory bullet points.
 * Categorize into OS specific and hardware dependent issues (if applicable).
 * Troubleshooting Azure virtual machines
 * Logs and troubleshooting Docker
 * Troubleshooting Azure virtual machines
 * Logs and troubleshooting Docker



Release notes

 * Release notes describe new features and bug fixes for software.
 * 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.
 * Slack Release Notes
 * Slack Release Notes
 * Slack Release Notes



White paper




Datasheet

 * A datasheet is a document that describes features and technical specifications of a product.
 * Datasheets should be brief; try limiting the document to one or two pages
 * Include wiring diagrams, graphics, and illustrations
 * Access control panel datasheet
 * Access control panel datasheet
 * Access control panel datasheet



Technical specification

 * A Technical specification describes the standards that a software/product must meet.
 * On Writing Tech Specs
 * Wise Words About Writing Technical Requirements Documents
 * Wise Words About Writing Technical Requirements Documents



Blog post

 * A type of website consisting of text, pictures, etc., in the form of journal entries, called posts. It is typically presented in chronologically reverse order and is updated frequently.
 * Have good design and easy navigation.
 * Get feedback for improvement.
 * Get feedback for improvement.



Abstract

 * The brief overview of a document.
 * Try to cover the most important points in a concise manner.
 * Mention the purpose of the doc and conclusions reached.
 * Writing an Abstract
 * Abstract Samples
 * Abstract Samples
 * Abstract Samples



Position paper




Conference presentations and panels



 * }

Additional information

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