Howto Documentation Guidelines

Purpose

The Howto categories are the right place to document more complex tasks. These are for things that involve multiple different modules, or need to describe concepts and go into lots of detail.

A howto is ideal for things like:

  • How to run Tryton using Docker (what steps are required, what commands need to be run and what does each one do)
  • How to import initial stock (how to create products, set proper cost prices, and create the initial internal shipment from the supplier location)
  • How to organise warehouse locations (including what strategies can be used, what are their pros and cons, what performance concerns are there and what can be done to avoid them)

Each howto should focus on a single topic, links to related topics, or other documentation can always be included when needed. It is much better to add documentation into the right place, and then link to it, to avoid duplicating documentation.

General Style

Consistency

Try and be consistent with how other howtos have been written. Read through some of the existing howtos to get an idea of their style and how they have been structured. This will make all the howtos feel familiar to the readers and help them get the most out of them.

Audience

When writing your howto try and remember which audience the document is intended for. There are separate sub-categories for different audiences so try and submit your howto into the right place.

Formatting

The editor allows you to format the howto as required. It has buttons that can make text bold or italic, and allows you to insert things like links, bullet and numbered lists. Use these as appropriate.

warning You may want to write your howto offline, and then copy and paste it when you are ready to submit it. If you are doing this then you can use the editor to see how the different styles are represented in plain text.

Sections

Ideally the howto should be structured in a logical way, with its parts split up into appropriate sections and subsections.

Section are introduced by a section title that uses one or more # symbols at the start of the line. The number of # symbols indicates the level of the section.

For example:

# Main Section

## Subsection

## Subsection

### Subsubsection

# Next Section

Table of Contents

It is often a good idea to add a table of contents to the howto. This will be automatically generated from the howto's sections if you include, on the first line:

<div data-theme-toc="true"></div>