Wiki source code of Documentation Guide
Last modified by Eleni Cojocariu on 2025/10/17 14:02
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | == General Remarks == | ||
| 6 | |||
| 7 | This document is meant to provide best practices on how the XWiki.org documentation should be written and maintained. | ||
| 8 | |||
| 9 | On XWiki.org documentation efforts usually go towards: | ||
| 10 | |||
| 11 | * Fixing bugs. | ||
| 12 | * Improving existing documentation. | ||
| 13 | * Keeping pages up to date with the latest changes in XWiki. | ||
| 14 | * Creating new documentation for new features, applications, procedures, etc. | ||
| 15 | * Refactoring documentation pages to the new location. | ||
| 16 | |||
| 17 | As of September 2025, documentation is being refactored: we are moving content to the [[Documentation for the XWiki Platform>>xwiki:Doc.WebHome]] location and applying the [[Diataxis>>https://diataxis.fr/]] framework. Currently, documentation can be found in three places: | ||
| 18 | |||
| 19 | * [[Documentation for the XWiki Platform>>xwiki:Doc.WebHome]] (the "/Doc" page): the new location, where several pages have already been converted. | ||
| 20 | * [[Documentation>>xwiki:Documentation.WebHome]] (the "/Documentation" page): old location from the main wiki, where unconverted documentation pages are still located. | ||
| 21 | * [[Extensions>>https://extensions.xwiki.org/xwiki/bin/view/Main/WebHome]] (the Extension sub-wiki) : where unconverted extension documentation pages are still located. | ||
| 22 | |||
| 23 | During this migration, sections or whole pages content from both "/Documentation" and Extension sub-wiki have already been moved to "/Doc". In their original locations, these sections have been replaced with links pointing to the newly converted pages. Over time, both the main documentation and the extensions will be fully moved under "/Doc". | ||
| 24 | |||
| 25 | == Requirements == | ||
| 26 | |||
| 27 | The following things are important when contributing to documentation: | ||
| 28 | |||
| 29 | * Your will ;) | ||
| 30 | * Having basic English skills, as all documentation should be written in English (since you are reading this guide, your skills are more than enough). | ||
| 31 | * Testing every feature that you want to document in a [[wiki environment>>https://www.xwiki.org/xwiki/bin/view/Hosted/]] running an [[LTS version or beyond>>xwiki:Main.Support||anchor="HCommunitySupport"]]. | ||
| 32 | * Being registered as an XWki.org user (use the "Register" link on the top right). | ||
| 33 | * Understanding the concept of [[Diataxis>>https://diataxis.fr/]]. | ||
| 34 | * Following this guide. | ||
| 35 | |||
| 36 | == Minor Changes == | ||
| 37 | |||
| 38 | Sometimes you will encounter small issues in the documentation. Examples of minor changes include: | ||
| 39 | |||
| 40 | * Grammar or spelling errors | ||
| 41 | * Typing errors | ||
| 42 | * Broken links | ||
| 43 | * Revising or slightly rephrasing texts for clarity | ||
| 44 | * Other small, low-impact fixes that don't affect the overall structure or meaning of the page | ||
| 45 | |||
| 46 | Such bugs should be fixed directly on the page, without creating a [[Change Request>>dev:Community.DocGuide.OrganizationalRules.SaveChangeRequest.WebHome]]. You don't need approval, just fix them :) | ||
| 47 | |||
| 48 | When making minor edits, please remember to: | ||
| 49 | |||
| 50 | * Mark the changes as "minor". This way you don't send notifications to people following that page (by IRC, mail or RSS) each time you make a minor addition. | ||
| 51 | * Write a short summary describing the fix (e.g., "fixed typo", "fix broken link" etc.). | ||
| 52 | * It's preferable to click "Preview" when [[editing a page with the Wiki editor>>xwiki:Doc.XS.User.Flamingo.FlamingoSkin.EditPage.EditWikiEditor.WebHome]] to view your changes before you save the document. This prevents saving incorrect content and sending "spam" notifications to people who explicitly configured their settings to receive minor ones. | ||
| 53 | |||
| 54 | == Major Changes == | ||
| 55 | |||
| 56 | Major changes are edits that impact the structure, organization or content of the documentation. Examples include: | ||
| 57 | |||
| 58 | * Creating new documentation (documenting a new feature or adding content to an existing feature). | ||
| 59 | * Refactoring a documentation page to follow the new [[organizational rules>>dev:Community.DocGuide.OrganizationalRules.WebHome]] and the [[new style rules>>dev:Community.DocGuide.DocumentationStyle.WebHome||anchor="HNewStyleRules"]] of the Documentation Guide. | ||
| 60 | * Restructuring navigation, moving content between locations, reorganizing sections. | ||
| 61 | * Updating many pages at once. | ||
| 62 | |||
| 63 | For these cases, you must follow the new rules in this Documentation Guide. It is recommended that major edits you are unsure of are saved in a [[Change Request>>dev:Community.DocGuide.OrganizationalRules.SaveChangeRequest.WebHome]], so that they can be properly reviewed and validated before being published. | ||
| 64 | |||
| 65 | {{comment}} | ||
| 66 | == Place the Page Coorectly in the Navigation Tree == | ||
| 67 | === Order of Pages in Navigation Tree === | ||
| 68 | |||
| 69 | Once you positioned the page in the navigation tree, you should check how it fits with the order of its other siblings. Ideally, the following criteria should be considered when positioning the page in the navigation tree: | ||
| 70 | |||
| 71 | * List pages from most useful to less useful, considering how often a feature is used | ||
| 72 | * Use the [[Common Criteria>>||anchor="HCommonCriteria"]] to help decide. | ||
| 73 | {{/comment}} | ||
| 74 | |||
| 75 | {{comment}} | ||
| 76 | == Create Landing Pages == | ||
| 77 | === Highlights === | ||
| 78 | |||
| 79 | Criteria for defining which documentation pages should be included in the highlighted section of landing pages: | ||
| 80 | |||
| 81 | ==== Common Criteria ==== | ||
| 82 | |||
| 83 | * Relevant pages to newcomers. | ||
| 84 | * Use [[Pages that are frequently accessed>>https://forum.xwiki.org/t/what-documentation-pages-would-you-like-to-see-updated/15133/22]] as a reference. | ||
| 85 | * Pages that address common issues. | ||
| 86 | * Pages that cover essential topics (useful for many situations, containing a lot of important information). | ||
| 87 | |||
| 88 | ==== Specific Criteria for each Type of Landing Page ==== | ||
| 89 | |||
| 90 | * For the extension landing page: | ||
| 91 | ** Include highlighted pages for each target, if there are pages that cover essential topics for that specific target. For example, if the highlights already include pages for users, but there are also important pages for admins, (e.g., how to enable the extension) those should be highlighted as well. | ||
| 92 | * For the sub-extension landing page: | ||
| 93 | ** The main how-tos of the essential topics of the sub-extension | ||
| 94 | * For target specific landing pages: | ||
| 95 | ** Focused on the specific target audience | ||
| 96 | |||
| 97 | TODO: template for landing pages in order to be easier to apply | ||
| 98 | {{/comment}} | ||
| 99 | |||
| 100 | == Start contributing == | ||
| 101 | |||
| 102 | After you read and understand how you should create and modify documentation you can start contributing yourself. Not sure what to work on? | ||
| 103 | |||
| 104 | * 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]]. | ||
| 105 | * You may also check the [[List of all violations>>xwiki:DocApp.Code.Violations.WebHome]] and fix them (if any). |
