Apply Diataxis

Apply Diataxis to the Page

To apply Diataxis: 

1. Identify the Diataxis type of the content you're writing: "Tutorial", "How-to", "Reference", or "Explanation".
2. Identify the target audience: User, Administrator, or Developer.
3. Choose the right location for the page, based on the type and audience identified above.
4. Create the documentation page at that location.
5. Complete the page's structure fields according to its documentation type, according to apply Diataxis to the content.

Apply Diataxis to the Content

How-to

• Start the How-to with a concise sentence that describes what the reader will achieve and, when useful, provides context beyond the title. Include a link to a relevant Explanation page in the first sentence whenever possible, so readers can learn more about the topic.
• Any step in a How-to must start with a verb and each step is an item of a numbered list.
• Steps should be accompanied by suggestive screenshots whenever they help guide the reader through the procedure.
• Include a final step that describes the expected result after completing the procedure. This step must include a screenshot showing the expected final result.
• Don't add extra explanations, instead use the FAQ section to formulate questions and answers from the reader's POV.
• When there are several alternative ways to reach the same goal (e.g. several installation or deployment methods), create one How-to per alternative, plus an Explanation page above them that helps the reader choose between the alternatives.

Tutorial

• Any step in a Tutorial must start with a verb and each step is an item of a numbered list. Short example sentences at any step are allowed to illustrate what exactly needs to be done.
• Steps should be accompanied by suggestive screenshots whenever they help guide the reader through the procedure.
• Include a final step that describes the expected result after completing the procedure. This step must include a screenshot showing the expected final result.

Reference

• Use tables to describe structured information such as properties, parameters, types, supported values, or their descriptions. Tables should provide concise information and avoid unnecessary verbosity.
• For API reference pages, tables may be replaced by the code macro, and usage examples, short use cases should be provided as a best practice provide useful context for the API.
  • For each API element, provide a concise description of its purpose and document its relevant parameters, types, supported values, default values, and return values.
  • Use code examples to show how the documented API is used, especially for types, functions, configuration, or syntax that may not be sufficiently clear from a description alone.
• When documenting Rendering Macros or UIXPs, use the DocApp.Code.RenderingMacroClass and DocApp.Code.UIXPClass Object objects available. (These objects can technically be added to any documentation page type, but Reference pages are generally the most suitable page type when documenting a Rendering Macro or UIXP).
  • For rendering macros, see the Create a documentation page for a rendering macro guide.
  • For UIXPs, see the Create a documentation page for a UIXP guide.
• When documenting Confluence macros or Confluence plugins, use the   objects available:
  • For Confluence macros, see the Create a documentation page for a Confluence macro guide.
  • For Confluence plugins, see the Create a documentation page for a Confluence plugin guide.

Explanation

• Explanations-type pages are describing concepts, limitations, consequences, most of the time answering the question "Why".
• Start by clearly defining the topic and explaining why it matters or how it fits into the broader context.
• Explain the reasons behind how something works, including relevant design choices, trade-offs, limitations, or constraints.
• Link to relevant How-to and Tutorial pages when readers may need instructions for applying the concepts in practice. Link to relevant Reference pages when readers need precise details about the concepts or components being explained.
• If the page is located as a top-level page (meaning it is a "topic page"), it must be Explanation page type. The first sentence of the explanation page must include a link to the corresponding extension page on the Extension Wiki, if one exists. This is the same page referenced by the extension ID.