4.4. User guides

Documenting for the end users of your project

Documentation for users

If your project becomes more and more complex you won’t be able to avoid to explain people how to build and use your product. Good user guides make a big difference in the success of open source projects. It does not only introduce the project and raise excitement for the product but save you and your contributors a lot of support work e.g. by giving answers to common problems and describing how to avoid them.

Minimal viable user documentation The user documentation should serve the purpose to help people to build your product and describe how to use it. The open source community is very diverse and so are projects, products and the respective user documentations. However, here are some general rules for a minimal viable user documentation:

Content

  • Table of content
  • Bill of material (see chapter 4.2)
  • Building instructions/Assembly guide/Recipe
  • How to use your product
  • common problems and how to solve them
    • during building/assembly
    • during usage

in general

  • Focus on what users can do with your project/product
  • Keep it simple and follow a logical hierarchy
  • Use a clear and simple language

Visuals Visuals are a great way to illustrate complicated assembly procedures and to show how a project/product is used. Use images, screenshots, schematic drawings, gifs or videos in your user documentation to improve it.

Tutorials and examples Show how your project/product can be used. Write/record (multi-level) tutorials and provide example use cases for others to follow along and learn. Tutorials are also a great way for introducing and showcasing new features.

Frequently asked questions - FAQ You are annoyed by users asking the same questions again and again? Well, how about writing a FAQ section and answer them right away? A FAQ list can grow over time according to user feedback.

Formats

As mentioned in the previous section, different groups need different formats. For users export formats such as STP, STL or PDF are appropriate. They can be read/interpreted by different systems and are sufficient to produce the design.

Assignment: Write a minimal viable documentation for users

  • If you do not yet have a bill of materials/tools/skills, write them
  • Write building instructions/assembly guide/recipe
  • Write something about how to use your hardware, try to include common pitfalls

Resources

  • https://github.com/openUC2/UC2-GIT/tree/master/TUTORIALS
next: Developer guides  

Help us improve content and suggest changes to this page.