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 must link XWiki concepts to their corresponding documentation pages whenever such documentation exists. If a page mentions an XWiki concept, feature, term, or functionality that has a dedicated documentation page, the concept should be linked directly to that page. The link should be applied to the relevant wording within the sentence, rather than added as a separate or generic link.
  • For example, if a page mentions exporting content as XARs, the wording referring to XAR export should link to the corresponding XWiki documentation page about exporting content in XAR format.
• 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

When you need to enumerate items in the documentation pages, you should use bullet points rather than displaying multiple items on a single line. Bullets improve readability 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

Avoid Duplicated Content

The same information must not be stated on two pages, however differently it is worded. If the same text, steps in a how-to, or images are repeated in two or more places, give that content a single home and link to it from the others.

• Prefer a visible page. Where the repeated content is meaningful on its own, restructure so that it becomes a page of the documentation tree: a navigation step that several how-tos open with becomes its own how-to that each procedure opens by linking to (for example Open the AntiSpam Application), and a page whose section is repeated elsewhere is split into two smaller pages, the shared one linked from both. A visible page is reachable from the navigation panel and from search, it answers a reader goal on its own, and a later author cannot duplicate it again by failing to notice that the content is shared.
• Otherwise, use the display macro with a hidden page, as described in the Macros section.

Repeated steps deserve particular attention, because a step carries its screenshot with it: the same image is attached to every page, and the copies are then free to drift apart as one of them is re-captured. Two comparisons find this without needing any judgement: line up the first step of the how-tos that share a parent page, and check that no attachment name is used by more than one page.

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, when no restructuring can give the repeated content a visible page of its own (see Avoid Duplicated Content). 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).