Wiki source code of Documentation Guide
Last modified by Eleni Cojocariu on 2026/08/26 11:17
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | == Where to Start == | ||
| 6 | |||
| 7 | Pick the entry point that matches what you are doing. Each one is a step-by-step flow that links out to the rules it depends on: | ||
| 8 | |||
| 9 | * Writing a page that does not exist yet → [[Create New Documentation – Flow Guide>>Community.DocGuide.CreateNewDocumentation.WebHome]] | ||
| 10 | * Changing a page that already exists → [[Update Existing Pages>>Community.DocGuide.UpdateExistingPages.WebHome]] | ||
| 11 | * Moving old content into the new ##/documentation## tree → [[Migrate and Refactor Documentation>>Community.DocGuide.MigrateDocumentation.WebHome]] | ||
| 12 | |||
| 13 | The remaining pages are the rules those flows refer to. Read them when a flow sends you there, or browse them directly: | ||
| 14 | |||
| 15 | * **Classifying and placing a page**: [[Apply Diataxis>>Community.DocGuide.Diataxis.WebHome]], [[Choose the Right Location for a Page>>Community.DocGuide.ChooseRightLocation.WebHome]] | ||
| 16 | * **Writing the page**: [[Page Structure>>Community.DocGuide.PageStructure.WebHome]], [[Documentation Style>>Community.DocGuide.DocumentationStyle.WebHome]], [[Page Titles and Page Names>>Community.DocGuide.ChooseRightLocation.PageTitlesNames.WebHome]], [[Versioning>>Community.DocGuide.Versioning.WebHome]], [[Working with Attachments>>Community.DocGuide.WorkingAttachments.WebHome]] | ||
| 17 | * **Publishing**: [[Save the Changes>>Community.DocGuide.SaveChanges.WebHome]] | ||
| 18 | * **Navigation and landing pages**: [[Documentation Navigation Panel>>Community.DocGuide.DocumentationNavigationPanel.WebHome]], [[Landing Pages>>Community.DocGuide.LandingPages.WebHome]], [[Highlights on a Page>>Community.DocGuide.HighlightsPage.WebHome]], [[Horizontal Menu Rules>>Community.DocGuide.HorizontalMenu.WebHome]] | ||
| 19 | * **Extension pages**: [[Handle Extensions.XWiki.org Pages>>Community.DocGuide.HandleExtensionPages.WebHome]] | ||
| 20 | * **Setting up to write**: [[Documentation Resources>>Community.DocGuide.DocumentationResources.WebHome]] | ||
| 21 | |||
| 22 | == Guideline Levels == | ||
| 23 | |||
| 24 | Pay attention to the level assigned to each guideline. The levels indicate how strongly a guideline should be followed: | ||
| 25 | |||
| 26 | * **Must**: Mandatory. You must follow this guideline. | ||
| 27 | * **Should**: Strongly recommended. You should follow this guideline unless there is a good reason not to. | ||
| 28 | * **Could**: Optional. You can follow this guideline if you find it useful or appropriate. | ||
| 29 | |||
| 30 | The levels have the following priority: **Must > Should > Could.** | ||
| 31 | |||
| 32 | == Contribution Types == | ||
| 33 | |||
| 34 | This guide is meant to provide best practices on how the XWiki.org documentation should be written and maintained. | ||
| 35 | |||
| 36 | On XWiki.org documentation efforts usually go towards: | ||
| 37 | |||
| 38 | * Fixing bugs. | ||
| 39 | * Improving existing documentation. | ||
| 40 | * Keeping pages up to date with the latest changes in XWiki. | ||
| 41 | * Creating new documentation for new features, applications, procedures, etc. | ||
| 42 | * Refactoring documentation pages to the new location: | ||
| 43 | ** As of September 2025, documentation is being refactored: we are moving content to the [[Documentation for the XWiki Ecosystem>>xwiki:documentation.WebHome]] location and applying the [[Diataxis>>Community.DocGuide.Diataxis.WebHome]] framework. During this [[migration process>>Community.DocGuide.MigrateDocumentation.WebHome]], documentation can currently be found in [[multiple locations>>xwiki:Documentation.WebHome||anchor="HWheretofindDocumentation3F"]]. | ||
| 44 | |||
| 45 | == Requirements == | ||
| 46 | |||
| 47 | The following things are important when contributing to documentation: | ||
| 48 | |||
| 49 | * Your will ;) | ||
| 50 | * Having basic English skills, as all documentation should be written in English (since you are reading this guide, your skills are more than enough). | ||
| 51 | * Testing every feature that you want to document in a [[wiki environment>>xwiki:Hosted.WebHome]] running an [[LTS version or beyond>>xwiki:Main.Support||anchor="HCommunitySupport"]]. | ||
| 52 | * Being registered as an XWiki.org user (use the "Register" link on the top right). | ||
| 53 | * Understanding the concept of [[Diataxis>>Community.DocGuide.Diataxis.WebHome]]. | ||
| 54 | * Following this guide. | ||
| 55 | |||
| 56 | == Choose What to Contribute To == | ||
| 57 | |||
| 58 | After you read and understand how you should create and modify documentation you can start contributing yourself. Not sure what to work on? | ||
| 59 | |||
| 60 | * Here's a [[list of pending to do's>>https://jira.xwiki.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+XINFRA+AND+component+%3D"www.xwiki.org"+AND+text+%7E+"Documentation"+AND+status+%3D+Open+ORDER+BY+priority+DESC&mode=hide]]. | ||
| 61 | * You may also check the [[List of all violations>>xwiki:DocApp.WebHome||anchor="HDocumentationviolations"]] and fix them (if any). |
