Skip to content

Technical Documentation Template

Info

  • When to use: use this template to create a new technical documentation entry, when a new development objective is defined.
  • How to use:
  • Copy this template to a proper location.
  • Rename and edit the copy, replacing the defult content, and deleting this header.
  • Progressively add content to each section below, using your "daily logs" as a source, every 7-15 days (adjust the interval to match your pace).
  • Sections that do not apply to the relevant development objective should be adapted, skipped, or removed (in this order). Your questions and suggestions are welcome! This template is based on the documentation scopes and audiences by Nicolás Méndez.

Tip

Use the daily logs template to keep detailed records and multimedial resources of your daily progress.

That material will be the main source of truth for this document, and is completely essential that you use them. Writing this document without source material will otherwise be very hard, and its quality will suffer.

Note

In some cases, you'll want to use this template to document a development objective which is listed below as part of a section (e.g. maintenance instructions). In this case and others, you'll need to adapt your content to the template and/or skip irrelevant headings. In general, you should be able to fit most kinds of content to the structure of this template.

Development objective

This section should include information about the documentation entry, including:

  • Title of the associated development objective: [insert name or replace title above]
  • Communication channel (e.g. Discord forum thread): [insert link]
  • Task tracking for the objective (e.g. GitLab issues): [insert link]

Overview

Overview documentation:

  • Type: Project documentation.
  • Audience: General community.
  • Content: Definition of the project or general objective. Explanation of what you did, what it is for. General overview.

Usage

Usage instructions:

  • Type: Technical documentation.
  • Audience: Users.
  • Content: Instructions for intended use, alternative usage modalities, usage restrictions (related to design choices, functional specification, and elementary operating principles).
  • Troubleshooting: Clarify if there might be any problem with the use of what you did and how can you adapt if you have a problem.
  • Precautions: Indicate if there are any precautions that must be taken.

Caveats and Limitations

  • Document type: Technical documentation.
  • Audience: General community.
  • Content: Current issues, potential problems the audience might encounter, and limitations of the work (both temporary or long-term). Enumeration and explanation of the most important problems, bugs, limitations, and other issues of this work. Instructions for how to avoid or patch them, proposals for possible fixes, links to GitLab issues, etc. It is prioritary that all "caveats" are documented, as this will help users understand the limitations of the work, and be offered to contributors as possible objectives.

Assembly

Assembly and manufacturing:

  • Document type: Technical documentation.
  • Required resources: parts, tools, environment, and skills required to build the project.
  • Audience: Makers, Users.
  • Content: Bill of Materials (materials and parts). Full description of assembly steps, parts, required knowledge, skills, time, and tools. Manufacturing instructions for custom parts, shopping list for comercially available parts and possible suppliers.
  • Precautions: Indicate if there are any precautions that must be taken.

Installation

Hardware and software installation instructions:

  • Document type: Technical documentation.
  • Tools and skills: tools required to install, setup, or callibrate the hardware and or software.
  • Audience: Technical support, Makers, Users.
  • Content: Complete description of installation steps and required knowledge, environment, number of people, skills, time, and tools. Links to learning resources. This applies to installation of software (e.g. OS, compilation, dependencies, drivers, etc.) and hardware (e.g. location requirements, operating conditions, etc.).

Interactions

Interfaces and interactions:

  • Document type: Technical documentation.
  • Audience: Makers, Users.
  • Content: Indicate how it connects to other parts of the robot, and all parameters relevant to those interactions and/or interfaces. Also comment in which section of the documentation you think your material goes (Assembly, Maintenance, Design, Development, etc.).

Maintenance

Maintenance procedures:

  • Document type: Technical documentation.
  • Audience: Technical support, Users.
  • Content: Required maintenance operations, frequency, tested replacement parts and compatible alternatives.
  • Precautions: Indicate if there are any precautions that must be taken.

Design

Design principles:

  • Document type: Technical documentation.
  • Audience: Developers, Contributors, Educators.
  • Content: Description of the overall design rationale. List of the main design choices and implications (e.g. functional compromises). Minimal explanation of the working principles. Specifications of the internal and external hardware or software interfaces. List of standards that apply.

Models

Hardware design files:

  • Document type: Source files.
  • Audience: Developers, Contributors.
  • Content: Design files with parts metadata, typically including: mechanical models (e.g. FreeCAD), schematics for electronics (e.g. KiCAD), technical drawings, specifications of parts and materials, etc. Distinguish between custom parts (e.g. developed as a result of this or another project), off-the-shelf parts (e.g. screws), or complex modules (e.g. a single board computer). Specification for all hardware interfaces.
  • Explanation of the part-naming scheme/convention.

Software

Software and firmware sources:

  • Document type: Source files.
  • Audience: Developers, Contributors.
  • Content: Original computer code for the programs required to operate the machine to its full capability. Detailed instructions to build and/or install the software and its dependencies and their specific versions. Specification for the programming interfaces (APIs) if any.

Development

  • Document type: Technical documentation
  • Audience: Developers
  • Content: Development flow and tools (e.g. IDEs, EDA, or CAD software), file formats, and guidelines used to develop the project. Description of setups for development and testing. Detailed description of the hardware modules and software, and corresponding source files. Tutorials and examples for how to get started or adding new modules.