Jump to content

Documentation/Technical documentation templates and suggestions

From mediawiki.org

Overview

[edit]

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?

[edit]

Genre is one way to classify the kind of writing you are doing. It can help determine the structure or form your writing will take.

Genres can usually be identified by sets of expectations and conventions. Documents written in a particular genre will typically have similar (if not the same) features -- though they may not share all the same expectations and conventions.

Tips for writing in genres

[edit]

The following table contains useful information to help you write in common genres.

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.
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.
Walkthoughs, how-tos and tutorials template
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.
Quickstart Guide Template
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.
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.

An API is a set of protocols and tools that aid easy communication between different parts of a software.

API Documentation template
Library A library is a piece of code written and organized in such a way that it can be used by multiple programs that have no connection with each other. Library template
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).
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.
In the field of technology, a white paper advocates the philosophy behind a product, software or technology.
A Technical specification describes the standards that a software/product must meet.
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.
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
A document which presents the author's opinions about a particular subject.
Tickets (task, bugs, features request, etc.)
A form (or document) used to report bugs and/or request new features.
  • Check if a similar bug has already been reported or a similar feature has already been requested.
  • Be descriptive and include the necessary links and resources.
Conference proposals

A document proposing a topic, finding or theory that constitutes a request for presenting the topic at a conference.

  • Have a clear purpose and objective.
  • Make sure to follow the conference's submission guidelines that are usually available on their website.
  • Consider the language and tone while drafting the proposal.
Conference presentations

A talk, workshop, poster, research paper, etc., that is presented at a conference.

  • Know your audience to make the presentation relevant.
  • Focus on the structure and design of the presentation.

See also

[edit]