Wiki source code of Documentation Guide

Last modified by Lucas Charpentier (Sereza7) on 2023/11/29 11:11

Show last authors
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 Either you write XWiki documentation on a regular basis or you want to make more simple contributions it's best you read the following guidelines.
9
10 On XWiki.org documentation efforts usually go towards:
11
12 * Fixing bugs
13 * Improving existing documentation
14 * Keeping pages up to date with the latest changes in XWiki
15 * Creating new documentation for new features, applications, procedures, etc.
16
17 {{info}}
18 See a list of [[pending documentation todos>>https://jira.xwiki.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+XWIKIORG+AND+status+%3D+Open+ORDER+BY+priority+DESC&mode=hide]].
19 {{/info}}
20
21 = Requirements =
22
23 The following things are important when contributing to documentation:
24
25 * Your will ;)
26 * Having basic English skills, as all documentation should be written in English (since you are reading this guide, your skills are more than enough)
27 * You must be registered as an XWki.org user (use the "Register" link on the top right)
28 * Reading this guide
29
30 = Fixing bugs =
31
32 Sometimes you will encounter trivial bugs, like:
33
34 * Grammar errors
35 * Typing errors
36 * Broken links
37 * Other "one" word bugs
38
39 Such bugs should be fixed directly in the page. You don't need to ask someone, just fix them :) Please, in doing so don't forget to:
40
41 * Mark the changes as "minor"
42 * Write a short comment describing the fix
43
44 That's all!
45
46 = Updating existing pages =
47
48 Any documentation can become obsolete or just not be good enough from your point of view. In these cases, if you want to upgrade/improve the documentation, you shouldn't make changes directly in the documentation page. Rewriting the documentation can take very long and nobody wants to have unbaked bread. Please proceed as follows:
49
50 1. Make sure the documentation you are planning to add applies to the [[suported versions>>xwiki:Main.Support#HCommunitySupport]].
51 1. If you're unsure about the changes you want to make, you may ask the [[XWiki forum>>Discuss]] or [[Chat>>Chat]] before starting the rework.
52 1. Create a new page on the [[Drafts>>Drafts.WebHome]] space.
53 1. If the work is a full rewrite of the documentation page, you can flag the original page as "under revision" with a link to the draft you have created:(((
54 {{code}}
55 {{info}}
56 This page is being reworked at the moment, therefore you shouldn't modify the present document. To bring changes to the page please see the current [[Draft >> your-draft-url]].
57 {{/info}}
58 {{/code}}
59
60 * Reference the original page from your draft:(((
61 {{code}}
62 {{info}}
63 This page is a draft for the [[PageName >> original-page-url]]. The rework should be completed until <date>.
64 {{/info}}
65 {{/code}}
66 )))
67 )))
68 1. If you are adding information about a new feature or documenting changes in an existing feature make sure you also specify the release during which those additions/changes were introduced, using the version macro (see above or below). This will make it easier for readers to see if the information applies to them.
69 1. Once you have completed the draft, please notify the community on the [[XWiki forum>>Discuss]].
70 1. After the community agrees with the improvements and possibly offers new suggestions you may replace or update the original page with the updated draft.
71 1. The draft must be removed after that, in order to avoid duplicate pages.
72
73 = When to create a new page =
74
75 Before building a new page you should first search for that piece of information in the existing documentation. You may find that:
76
77 * A similar page already exists and portraits the situation you were about to describe. Make sure you also check the [[Drafts page>>Drafts.WebHome]]. Somebody may be already working on a similar page. If so, you could contact her/him and help.
78 * There is a page on XWiki.org that only covers part of the message you were about to convey. You can write additional information to the existing page.
79 * There is no documentation on your choice of topic. At this point you may create a new page.
80
81 = How to create new pages =
82
83 Now that you've decided to create a new page you should take notice of the following steps:
84
85 1. If there are no similar pages on the [[Drafts page>>Drafts.WebHome]], add a link to your draft followed by a short description.
86 1. At this point you could inform the community on the [[user mailing list>>Community.MailingLists#HPublicMailingLists]] about your plans. Most probably you will get helpful suggestions and even find contributors.
87 1. After you have completed the draft, please notify the XWiki community on the [[user mailing list>>Community.MailingLists#HPublicMailingLists]].
88 1. After the community has reviewed the document and additional improvements have been made the original page can be replaced with the draft.
89 1. Make sure you remove the draft after the original page has been updated, in order to avoid duplicate pages.
90 1. If you are not replacing an original page, but want to create a new page altogether and you are not sure where it's best to add it you can ask on the [[user mailing list>>Community.MailingLists#HPublicMailingLists]] or on IRC what the best place is. The community will most likely point you to the right wiki & space.
91
92 = Text editing =
93
94 You've decided to make a new document or improve an existing one. Chances are you'll want to add new text and/or bring changes to existing paragraphs. When editing the text in a document it's best to:
95
96 * Write the page title in the title field
97 * Use headings to mark the different sets of information
98 {{info}}To ensure the best experience for assistive technology users, heading hierarchy should be under the page title, which means using only the H2 level and lower.{{/info}}
99 * Use bold to emphasize important pieces of text
100 * Use bullets to make content easier to skim through
101
102 When you're done typing don't forget to review your text for typos and/or mistakes before submitting it.
103
104 = List Items =
105
106 It's very frequent to have an item list and to have some images or tables to display inside a list item.
107
108 What not to do:
109
110 {{code language="none"}}
111 * Item 1
112 * Item 2
113
114 {{image reference="whatever.png"/}}
115
116 * Item 3
117 {{/code}}
118
119 The reason is that this breaks the list and the image will not be displayed inside the list item.
120
121 Instead you should write:
122
123 {{code language="none"}}
124 * Item 1
125 * Item 2(((
126 {{image reference="whatever.png"/}}
127 )))
128 * Item 3
129 {{/code}}
130
131 = Macros =
132
133 Macros can help you better visualize information within a page. You should use:
134
135 * The [[code macro>>extensions:Extension.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 langage) and in a lost of cases the wrong language will be found leading to bad syntax coloring.
136 * The [[info macro>>extensions:Extension.Info Macro]] to highlight important information
137 * The [[warning macro>>extensions:Extension.Warning Macro]] to let readers know of possible issues they might come across
138 * The [[toc macro>>extensions:Extension.TOC Macro]] to create a table of content for large documents covering a long array of information.
139
140 = Linking =
141
142 * Now that you have added text you should use links to point to other useful resources outside the page
143 * 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 ##wiki:Space.Name## notation 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.
144 * More information about links, including differences between the different syntaxes, can be found by reading the [[XWiki Syntax page>>xwiki:Documentation.UserGuide.Features.XWikiSyntax#HLinks]]
145 * If you wish to link to a file on GitHub you must use the ##~{~{scm}}## macro. The rationale is that this will allow us to change SCM without breaking all our URLs (which is what we experienced when we moved from Subversion to GitHub). Here's how it works:(((
146 Examples:
147
148 {{code language="none"}}
149 {{scm/}}
150
151 {{scm project="xwiki-rendering"/}}
152
153 {{scm project="xwiki-commons" path="xwiki-commons-core/pom.xml"/}}
154
155 {{scm branch="stable-3.1.x" path="xwiki-platform-core/pom.xml"/}}
156
157 {{scm path="xwiki-platform-core/pom.xml"/}}
158
159 {{scm branch="stable-3.1.x" path="xwiki-platform-core/pom.xml"}}With **label**{{/scm}}
160
161 {{scm branch="stable-3.1.x" path="xwiki-platform-core/pom.xml" raw="true"/}}
162 {{/code}}
163
164 Parameters:
165
166 |= Parameter name |= Default value |= Description
167 | user | xwiki | the github user
168 | project | xwiki-platform | the repository name in the provided user
169 | branch | master | the branch or tag
170 | raw | false | UI or raw content
171 | path | empty string | the resource in the repository
172 )))
173
174 = Literals / computer terms =
175
176 It is recommended to use the ## notation for literals and computer terms.##
177
178 For example, instead of saying {{code language="none"}}This is the "age" xproperty{{/code}}, you'd write {{code language="none"}}This is the ##age## xproperty{{/code}}.
179
180 = Screen shots / Images =
181
182 It is recommended to use images to illustrate the content you are writing about. There are some practices it's best to follow with respect to images:
183
184 * Always use the {{{{{image}}}}} macro. This allows to have a common style for all images (borders, ability to click when the image is resized, etc). For example:(((
185 {{code language="none"}}{{image reference="someimage.extension" width="350px"/}}{{/code}}These lines...
186 )))
187 * Use names that are suggestive
188 * Only have screenshots of the latest skin
189 * You should save your images only as PNG.
190 * To give documentation a homogeneous look we recommend using four standard width sizes for screenshots:
191 ** Extra Large: width of the image : 960px; (used for whole interface screens)
192 ** Large: width of the image : 650px;
193 ** Medium: width of the image : 350px;
194 ** Small: width of the image : 150px;
195 * You should add a piece of text in italics under images that describes what that image is about (by using the ##caption## parameter of the image macro)
196 * If your image is part of a bullet list, that image should be aligned to the text in the bullets. For this purpose we use(((
197 {{code}}
198 * Some text here(((
199 {{image reference="someimage.extension"/}}
200 )))
201 {{/code}}
202 )))
203
204 = Diagrams =
205
206 Whenever you need to add a diagram, you must:
207
208 * Use the [[PlantUML Macro>>extensions:Extension.PlantUML Macro]] and use one of the [[supported diagram types>>https://plantuml.com/]].
209 * Use the ##bluegray## theme (see the example below).
210
211 This has several benefits:
212
213 * Consistent diagram L&F across xwiki.org
214 * The source of the diagram is in the wiki content and thus can be easily modified (it wouldn't be the case with a screenshot of a generated diagram for example)
215 * Makes it easier to edit diagrams as otherwise you would need to use the same tool as the one used by the person who generated the diagram to be modified (provided he attached the source to the page, see previous point)
216
217 Example:
218
219 * [[URL Architecture >>xwiki:Documentation.DevGuide.Architecture.URL Architecture.WebHome]]
220 * Content:(((
221 {{code language="plantuml"}}
222 {{plantuml}}
223 @startuml
224 !theme bluegray
225 start
226 -> URL;
227 :Routing Filter;
228 floating note left
229 Executed as the first
230 Filter in web.xml
231 end note
232 floating note right
233 Parse URL and check if there's
234 a Resource Reference Handler to
235 handle the Resource Type
236 end note
237 if (Resource Reference Filter?) then (Yes)
238 :Resource Reference Handler Servlet;
239 :Resource Reference Handler;
240 note: e.g. WebJarsResourceReferenceHandler
241 kill
242 else (No)
243 partition "Legacy Action Handling" {
244 :Evaluate rest of web.xml;
245 split
246 :Legacy Action Servlet;
247 kill
248 split again
249 :Other Servlets;
250 kill
251 end split
252 }
253 endif
254 @enduml
255 {{/plantuml}}
256 {{/code}}
257 )))
258
259 Here are a few tools to help produce and test plantuml diagrams:
260
261 * http://www.plantuml.com/plantuml
262 * https://www.planttext.com
263 * https://plantuml-editor.kkeisuke.com/
264
265 = Affected Versions =
266
267 When documentation is added that depends on the versions of XWiki or the released extension (in case of XWiki, [[for XWiki versions ~>= LTS version>>#HRemovingolddocumentation]]), this must be specified using the [[{{code language="none"}}{{version}}{{/code}} macro>>xwiki:Macros.VersionMacro]]
268
269 Example result:
270
271 {{image reference="versions.png"/}}
272
273 See the [[Version macro page>>xwiki:Macros.VersionMacro]] for more examples.
274
275 = Syntax =
276
277 * When you're not sure about the appropriate syntax you should use please consult the [[XWiki Syntaxes Page>>xwiki:Documentation.UserGuide.Features.XWikiSyntax]]
278 * Pages should be written in 2.1 syntax
279 * When converting a page from 1.0/2.0 to 2.1 syntax you should look at the end result and make sure nothing was broken in the process. Double check that comments have been properly converted as well.
280 * Avoid using HTML code and use [[XWiki Syntax>>xwiki:Documentation.UserGuide.Features.XWikiSyntax]] instead
281
282 = Preview & Save =
283
284 * It's preferable to click "Preview" when editing a page to view your changes before you save the document. This way you don't send notifications to people following that page (by IRC, mail or RSS) each time you make a minor addition.
285 * When changing a document you should write a short comment describing the changes you introduced. This way everyone can stay up to date with no need to check the "History" tab.
286 * If you are making small improvements make sure you check the "Is minor edit" checkbox before saving your page.
287
288 = Attachments =
289
290 * If you want to replace an attachment with a newer version you shouldn't delete the old attachments. Just save the new attachment under the same name and a new version will be created for the old attachment.
291 * File extensions should be in lowercase letters (this is not mandatory, but it's recommended for better versioning). E.g. If you use both upper and lower cases for //Image.//**png** & //Image.//**PNG** you'll get two different attachments with separate versions.
292 * If you're using multiple words to name your attachments, it's best that each word starts with a capital letter, making the file name easy to scan. E.g.: CreagePage.png, RemoveSpace.png, TopBarRenameToucan.png
293
294 = Making your page accessible on the wiki =
295
296 Once you've successfully created and edited a page it's equally important to make sure other people can reach that page as well.
297
298 * When you create a new document it's best to set a parent for that page. Setting parents to documents allows for easy creation of hierarchies, as deep as you want.
299 * You should also add links from other pages towards the document you have just created.
300
301 = Moving a page =
302
303 If you decide to move a page you should not remove the old page altogether. Use the old document to point to the new page. This way users that have the old link saved can still reach the information they are interested in by finding their way to the new URL. You can use the [[redirect syntax>>snippets:Extension.Redirect]] to link the new page from the old page.
304
305 = Removing old documentation =
306
307 The xwiki.org community only [[supports the LTS and beyond>>xwiki:Main.Support#HCommunitySupport]]. Thus the documentation on xwiki.org should be aligned and only document the LTS and beyond.
308
309 The consequence is that documentation gardening should be done to:
310
311 * Remove documentation and [[versions macros>>#HAffectedVersions]] that only affects old versions of XWiki.
312 * Remove mentions of old XWiki versions by removing the [[versions macros>>#HAffectedVersions]] around valid content. This avoid the xwiki.org documentation to be littered with references to old (not supported) versions of XWiki.
313
314 = Start contributing =
315
316 Now that you've read how you should create and modify documentation you can start contributing yourself. Not sure what to work on? 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+"xwiki.org"+AND+status+%3D+Open+ORDER+BY+priority+DESC&mode=hide]].

Get Connected