• Guides
  • How we structure our documentation

How we structure our documentation

Whether you’re writing documentation for FreeSewing or merely trying to find what you are looking for, understanding how we structure our documentation can help you find your feet and figure out what goes where.

Types of documentation

Our documentation is divided into four different types:

  • Tutorials are lessons that lead you through a series of steps to complete a project.
  • Guides tell a story to further your understanding of a specific topic.
  • Howtos give you concrete steps to solve a common problem or challenge.
  • Reference holds technical descriptions of the underlying technology and how to make use of it.

Each time you write documentation, you have to ask yourself: Is it a tutorial? Is it a Guide? Is it a Howto? Or, is it Reference documentation?

If you find it hard to answer that question, the illustration below might help you figure out where your documentation should go based on what it’s trying to accomplish:

A graphic showing a visual representation of our documentation

  • Write a Tutorial is your aim is to help people learn the platform
  • Write a Guide if your aim is to further people’s understanding of a topic by going a bit deeper
  • Write a Howto if your aim is to help people accomplish a task
  • Write Reference documentation to detail how things work under the hood
  • Refer people to Discord or GitHub for things that are not (yet) covered in our documentation
Based on a talk by Daniele Procida

This structure is loosely based on this talk by Daniele Procida at PyCon AU 2017.