Documentation Style

Whenever you create or edit a documentation page, it is important to follow a consistent style. The rules below provide guidance on structure, formatting, and terminology.

Content Writing Guidelines

Syntax

• Pages must be written in xwiki/2.1 syntax.
• When you're not sure about how to use the syntax, please consult the XWiki Syntaxes Page.
• When converting a page from xwiki/2.0 to xwiki/2.1 syntax, you should look at the end result and check for conversion errors.
• Avoid using HTML code and use XWiki Syntax instead.

UI Elements

Whenever referring to a UI element in the documentation (such as buttons, menu items, tabs), you must use "quotes" to distinguish it from the rest of the text. For example: Select the content Syntax you want to use from the "Page Syntax" section inside the "Page Information" Panel. or   Click the "Edit" button.

XWiki Terminology

A word is considered "terminology" if it has a special meaning in XWiki, other than in the English dictionary (example: "Panel" when referring to the left or right Panel in XWiki, "Sheet" when referring to the XWiki Sheet etc.).

Whenever writing a word that is XWiki Terminology, you must write it in plain text and uppercase, until a proper Glossary strategy is implemented. The Glossary Application on xwiki.org will later help automatically write and link to explanations for the terminology words.

Glossary

All XWiki terminology must be collected in the Glossary Terms page until the Glossary Application is properly configured. All entries in the Glossary must have pages as Diataxis Explanation pages, located in the place where that explanation makes sense in the documentation hierarchy.

Literals / Computer Terms

It is recommended to use the ##notation## for literals and computer terms.

For example, instead of saying This is the "age" xproperty, you'd write This is the ##age## xproperty.

No Styles

When creating or modifying page content, please don't use styles. The reason is that we want that pages only contain content and that they all look the same.

For example, don't write:

(% style="font-family:Georgia,serif; font-size:14px" %)From XWiki WebPreferences page: Global Administration → Look & Feel → Presentation → subsection Header → Title.(%%)

but instead:

From XWiki WebPreferences page: Global Administration → Look & Feel → Presentation → subsection Header → Title.

Linking

• You should use links to point to other useful resources outside the page.
• Don't use URLs for links to xwiki.org. If the URL format or the domain get changed, the links will be broken. You should use the link reference syntax instead. To easily get the "id" of the page you are linking to, scroll to the bottom of that page, select the Information tab, and copy the value in the Page Reference field.
  • If the link is meant to work only inside the same Wiki, use reference displayed by default, which is relative to the current Wiki.
  • If the link needs to work across all Wikis, use the global (absolute) reference.
• More information about links, including differences between the different syntaxes, can be found by reading the XWiki Syntax page.
• If you wish to link to a file on GitHub, you must use the {{scm}} macro (SCM Macro). The rationale is that this allows us to change SCM without breaking all our URLs (which is what we experienced when we moved from Subversion to GitHub).

List Items

You may use bullets to create lists and make content easier to skim through. It's very frequent to have an item list and to have some images or tables to display inside a list item.

What not to do:

* Item 1
* Item 2

{{image reference="whatever.png"/}}

* Item 3

The reason is that this breaks the list (by creating 2 lists) and the image will not be displayed inside the list item.

Instead, you should write:

* Item 1
* Item 2(((
{{image reference="whatever.png"/}}
)))
* Item 3

Other Best Practices

Macros

Macros can help you better visualize information within a page. You should use:

• The code macro to insert pieces of code. Make sure you always use the language parameter as otherwise you're going to make it slower than it should be (the content will be analyzed to infer the language) and in a lot of cases the wrong language will be found leading to bad syntax coloring.
• The display macro to avoid duplicated content across pages. If the same text, steps in a how-to, or images etc. are repeated in two or more places, create a new page with the repeated content. Hide this page, and in other pages use only the display macro to link to the hidden page. (For example: Change the Syntax, Change the Syntax when Editing ; the hidden page: Convert to a Syntax).