Project documentation structure

Types of content

Following the Diataxis method, the docs content is divided into these four content types:

	Tutorials	How-to guides	Reference	Explanation
	introduce, educate, lead	guide, demonstrate	states, describes, informs	explains, clarifies, discusses
answers the question	“Can you teach me to…?”	“How do I…?”	“What is…?”	“Why…?”
oriented to	learning	tasks	information	understanding
purpose	to allow the newcomer to get started	to show how to solve a specific problem	to describe the machinery	to explain
form	a lesson	a series of steps	dry description	discursive explanation
analogy	teaching a child how to cook	a recipe in a cookery book	a reference encyclopaedia article	an article on culinary social history

Editing Content

The content types tutorials, how-to guides, and explanation are edited in AsciiDoc. However, AsciiDoc makes it hard to reuse content efficiently, so it might make sense to switch to DITA or another structured writing approach in the future.

Since reference documentation needs to adhere to a strict structure, it is edited in YAML. Using a Ruby script, the YAML file gets compiled into the desired output. This allows for more flexible reuse, since AsciiDoc and Liquid only provide cumbersome mechanisms for reuse.

For further information on editing content, have a look at the Style Guide.

Content structure: Where to store content?

Due to the different requirements in terms of versioning and target audience, the docs are stored in two places:

• Tutorials, how-to guides, and explanation are stored in the Metanorma.org repository. These types of topics should be created by a technical writer.
• The reference docs are stored in the respective flavor repository for the following reasons:
  • Authoring workflow: The developer that makes changes to the flavor needs to update the reference document before releasing a new version. This also leads to version-specific documentation and makes it easier to distinguish which version supports which features.
  • Forking: If someone forks a flavor repository, they have the reference documentation on their local machine. This simplifies looking things up & ensures offline-access.

Related links

• Flavor repository link list
• Documentation Style Guide
• Documentation Templates