Technical Documentation

Practices for writing technical documentation

Here are some best practices for writing clear and effective technical documentation:

• Know Your Audience: Understand who will be reading the documentation (developers, end-users, stakeholders) and tailor the content to their level of expertise and needs.
• Clear Structure and Organization: Use a logical structure with clear headings and subheadings. Maybe include a table of contents for easier navigation, especially for lengthy documents.
• Clarity and Conciseness: Break down complex concepts into manageable sections or steps.
• Consistency: Maintain consistent terminology, tone, and style throughout the document. Also use a consistent format for headings, code blocks, and lists.
• Code Examples: Include code snippets to demonstrate concepts and provide real-world examples.
• Maintain and Update: Regularly review and update the documentation to keep it current with any changes in the project or software.

Useful links

• Google technical writing
• GitLab doc style guide

Presentation of Diatixis

The Diataxis framework is a comprehensive approach to organizing technical documentation.

It divides documentation into four distinct categories: Tutorials, How-To Guides, Reference, and Explanation.

We used this framework to create clear the current documentation:

Tutorials

• Purpose: Tutorials are designed to guide users step-by-step through a series of tasks to achieve specific objectives. They are hands-on and project-based, addressing the initial learning stage.

• Principles:

  • Focus on Specific Goals: Ensure each tutorial has a clear, achievable goal or project.
  • Step-by-Step Instructions: Provide detailed, sequential steps that users can follow easily.
  • Assumptions: State any assumptions about the user’s existing knowledge and environment setup.
  • Interactive Components: Include code snippets, visuals, and interactive elements to facilitate active learning.

How-To Guides

• Purpose: How-To Guides are task-oriented documents that provide specific instructions on how to accomplish particular tasks. These are practical and focus on solving real-world problems.

• Principles:

  • Problem-Solution Approach: Clearly define the problem and provide concise, practical solutions.
  • Simplicity: Keep instructions simple and focused on one task at a time.
  • Ensure Accuracy: Regularly update guides to reflect the current state of the software or system.
  • Alternate Scenarios: Cover common variations or exceptions where applicable.

Reference

• Purpose: Reference documentation serves as a detailed, structured source of all technical details, APIs, functions, commands, etc. It is aimed at providing precise information that users can look up as needed.
• Principles:
  • Organized Structure: Use clear headings, tables, and indexing to make information easy to locate.
  • Detail-Oriented: Include thorough and accurate details about syntax, parameters, return values, and examples.
  • Consistency: Maintain a consistent format and terminology throughout the reference documents.
  • Searchability: Ensure the documentation is easily searchable with appropriate keywords.

Explanation

• Purpose: Explanation documentation provides in-depth understanding and context about concepts, processes, or systems. It addresses the “why” behind the technology.
• Principles:
  • In-Depth Discussion: Explore the background, theory, and rationale behind concepts.
  • Clear Context: Explain how different parts of the system interact and the reasons for specific design choices.
  • Comparisons: Provide comparisons with alternatives to give a clear perspective.
  • Visuals and Examples: Use diagrams, flowcharts, and examples to clarify complex ideas.

Automated Documentation Generation

Automated documentation generation refers to the process of converting code comments and annotations directly into comprehensive, formatted documentation.

This is particularly useful for API documentation, where function definitions, parameters, and return values need to be clearly documented.

Benefits of Automated Documentation

• Consistency: Ensures that the documentation and code are always aligned.
• Efficiency: Saves time by reducing the need to manually write and update documentation.
• Accuracy: Minimizes the risk of outdated or incorrect documentation.
• Maintenance: Automatic updates with code changes help keep documentation relevant and up-to-date.

Tools for Automated documentation

• Doxygen : Primarily used for C++, but also supports C, C#, Java, Python, and other languages.
• Sphinx : Primarily used for Python, but can be configured for other languages.
• Swagger : mainly used for RESTful APIs. Defines API endpoints, request/response formats, and generates interactive API documentation.

To be Continued

🧰 To find out more, visit our how to page on documentation.

• ♾ Please consider NextGen doc2pdf step
• ♾ Please consider NextGen mkdocs step
• ♾ Please consider NextGen markdown-lint step