How to Create Technical Documentation

ref: slite

Technical documentation refers to the documents that describe the features and functionalities of a product

Types of of technical documentation:

  1. Process-based
    process-based documentation describes the development of a product. It doesn't focus on the end product, but outlines the different steps, data and events that make up its progress and evolution.
    This kind of technical writing normally stays internal and wouldn't be of much use or interest to customers or end-users
    It's useful because it describes the different stages in a product's lifecycle.
    - Project proposals, objectives & timelines
    - General project standards & expectations
    - Project plans, project outlines, project summaries & project charters
    - Product roadmaps & plans for product releases
    - Project reports & updates
  2. Product-based
    product-based documentation, sometimes referred to as user documentation, provides details about what a finished product is and how to use it. Rather than explaining the development process, it focuses on the end product.
    - User guides, tutorials, installation manuals, troubleshooting manuals, FAQs, knowledge bases, wikis & other learning resources
    - Release notes
    - User experience (UX) documents
    - API documentation

How to write technical documentation ?

  1. Do your research
    Ask yourself and your colleagues questions like:
    - What do we want our technical documentation to cover?
    - What goals or objectives do we want our technical documentation to accomplish?
    - What information or documentation do we currently have to work with?
    - Will we be using any specific software, tools or style guides in the development of our technical documentation?
    - When do we need to finish our technical documentation by?
  2. Consider documentation design
    It’s a good idea to categorize and sub-categorize your information so it can be looked through quickly. It’s even better if your documentation has an effective search function or a dynamic table of contents that allows readers to quickly jump to the information they need.
  3. The writing process
    The best technical documentation is usually produced when:
    - Writers start with outlines
    - Writers make their documentation user-focused 
    - Writers get their work reviewed by other team members
  4. Test your documentation
    Once you’ve produced your finished technical documentation, it’s important to put it through a testing phase and check for organizational issues, confusing information, and usability problems.
  5. Publish & establish protocol for the future
    Publish your technical documentation for your users to take advantage of.
    Establish a protocol that details what needs to be done when new information needs to be added, changes need to be integrated or general maintenance needs to be made.