Hide last authors
Silvia Macovei 2.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
krokosjablik 1.1 2 {{toc/}}
Silvia Macovei 2.1 3 {{/box}}
krokosjablik 1.1 4
Silvia Macovei 2.1 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
Silvia Macovei 8.1 15 * Creating new documentation for new features, applications, procedures, etc.
Silvia Macovei 2.1 16
Silvia Macovei 4.1 17 {{info}}
Thomas Mortagne 17.1 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]].
Silvia Macovei 4.1 19 {{/info}}
20
krokosjablik 1.1 21 = Requirements =
22
Silvia Macovei 2.1 23 The following things are important when contributing to documentation:
krokosjablik 1.1 24
Silvia Macovei 2.1 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)
Manuel Smeria 12.4 27 * You must be registered as an XWki.org user (use the "Register" link on the top right)
Silvia Macovei 2.1 28 * Reading this guide
krokosjablik 1.1 29
30 = Fixing bugs =
31
Silvia Macovei 2.1 32 Sometimes you will encounter trivial bugs, like:
krokosjablik 1.1 33
Silvia Macovei 2.1 34 * Grammar errors
35 * Typing errors
36 * Broken links
37 * Other "one" word bugs
krokosjablik 1.1 38
Silvia Macovei 2.1 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:
krokosjablik 1.1 40
Silvia Macovei 2.1 41 * Mark the changes as "minor"
42 * Write a short comment describing the fix
krokosjablik 1.1 43
44 That's all!
45
Silvia Macovei 2.1 46 = Updating existing pages =
krokosjablik 1.1 47
Silvia Macovei 2.1 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:
krokosjablik 1.1 49
Silvia Macovei 12.3 50 1. Make sure the documentation you are planning to add applies to the two most recent releases.
Vincent Massol 17.2 51 1. If you're unsure about the changes you want to make, you may ask the [[XWiki forums & lists>>Discuss]] before starting the rework.
Manuel Smeria 12.4 52 1. Create a new page on the [[Drafts>>Drafts.WebHome]] space.
Sorin Burjan 3.1 53 1. Flag the original page as "under revision" with a link to the draft you have created:(((
Silvia Macovei 2.1 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 )))
Sorin Burjan 3.1 60 1. Reference the original page from your draft:(((
Silvia Macovei 2.1 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 )))
Silvia Macovei 12.1 67 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. This will make it easier for readers to see if the information applies to them.
Manuel Smeria 12.4 68 1. Once you have completed the draft, please notify the community on the [[user mailing list>>Community.MailingLists#HPublicMailingLists]].
Silvia Macovei 2.1 69 1. After the community agrees with the improvements and possibly offers new suggestions you may replace the original page with the updated draft.
70 1. The draft must be removed after that, in order to avoid duplicate pages.
krokosjablik 1.1 71
Silvia Macovei 2.1 72 = When to create a new page =
krokosjablik 1.1 73
Silvia Macovei 2.1 74 Before building a new page you should first search for that piece of information in the existing documentation. You may find that:
krokosjablik 1.1 75
Silvia Macovei 2.1 76 * 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.
77 * 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.
78 * There is no documentation on your choice of topic. At this point you may create a new page.
krokosjablik 1.1 79
Silvia Macovei 2.1 80 = How to create new pages =
81
Manuel Smeria 12.4 82 Now that you've decided to create a new page you should take notice of the following steps:
Silvia Macovei 2.1 83
84 1. If there are no similar pages on the [[Drafts page>>Drafts.WebHome]], add a link to your draft followed by a short description.
Manuel Smeria 12.4 85 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.
86 1. After you have completed the draft, please notify the XWiki community on the [[user mailing list>>Community.MailingLists#HPublicMailingLists]].
Silvia Macovei 2.1 87 1. After the community has reviewed the document and additional improvements have been made the original page can be replaced with the draft.
88 1. Make sure you remove the draft after the original page has been updated, in order to avoid duplicate pages.
Manuel Smeria 12.4 89 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.
Silvia Macovei 2.1 90
91 = Text editing =
92
93 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:
94
95 * Write the page title in the title field
96 * Use headings to mark the different sets of information
97 * Use bold to emphasize important pieces of text
98 * Use bullets to make content easier to skim through
99
100 When you're done typing don't forget to review your text for typos and/or mistakes before submitting it.
101
102 = Macros =
103
104 Macros can help you better visualize information within a page. You should use:
105
Vincent Massol 2.2 106 * The [[code macro>>extensions:Extension.Code Macro]] to insert pieces of code
107 * The [[info macro>>extensions:Extension.Info Macro]] to highlight important information
108 * The [[warning macro>>extensions:Extension.Warning Macro]] to let readers know of possible issues they might come across
109 * The [[toc macro>>extensions:Extension.TOC Macro]] to create a table of content for large documents covering a long array of information.
Silvia Macovei 2.1 110
111 = Linking =
112
113 * Now that you have added text you should use links to point to other useful resources outside the page
114 * 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.
Silvia Macovei 9.1 115 * More information about links, including differences between the different syntaxes, can be found by reading the [[XWiki Syntax page>>platform:Main.XWikiSyntax#HLinks]]
Vincent Massol 18.1 116 * 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:(((
117 Examples:
118
119 {{code language="none"}}
120 {{scm/}}
121
122 {{scm project="xwiki-rendering"/}}
123
124 {{scm project="xwiki-commons" path="xwiki-commons-core/pom.xml"/}}
125
126 {{scm branch="stable-3.1.x" path="xwiki-platform-core/pom.xml"/}}
127
128 {{scm path="xwiki-platform-core/pom.xml"/}}
129
130 {{scm branch="stable-3.1.x" path="xwiki-platform-core/pom.xml"}}With **label**{{/scm}}
131
132 {{scm branch="stable-3.1.x" path="xwiki-platform-core/pom.xml" raw="true"/}}
133 {{/code}}
134
135 Parameters:
136
137 |= Parameter name |= Default value |= Description
138 | user | xwiki | the github user
139 | project | xwiki-platform | the repository name in the provided user
140 | branch | master | the branch or tag
141 | raw | false | UI or raw content
142 | path | empty string | the resource in the repository
143 )))
144
Silvia Macovei 2.1 145 = Screen shots / Images =
146
147 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:
148
Vincent Massol 16.1 149 * 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:(((
Vincent Massol 13.1 150 {{code language="none"}}
Vincent Massol 18.2 151 {{image reference="someimage.extension" width="350px"/}}
Vincent Massol 13.1 152 {{/code}}
153 )))
Silvia Macovei 2.1 154 * Use names that are suggestive
Silvia Macovei 12.2 155 * Only have screenshots of the latest skin
Sorin Burjan 3.1 156 * You should save your images only as PNG.
Silvia Macovei 2.1 157 * To give documentation a homogeneous look we recommend using four standard width sizes for screenshots:
158 ** Extra Large: width of the image : 960px; (used for whole interface screens)
159 ** Large: width of the image : 650px;
160 ** Medium: width of the image : 350px;
161 ** Small: width of the image : 150px;
Vincent Massol 19.1 162 * 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)
Silvia Macovei 6.1 163 * 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(((
Vincent Massol 7.1 164 {{code}}
165 * Some text here(((
166 {{image reference="someimage.extension"/}}
Silvia Macovei 6.1 167 )))
Vincent Massol 7.1 168 {{/code}}
Silvia Macovei 6.1 169 )))
170
Silvia Macovei 2.1 171 = Syntax =
172
173 * When you're not sure about the appropriate syntax you should use please consult the [[XWiki Syntaxes Page>>platform:Main.XWikiSyntax]]
Silvia Macovei 10.1 174 * Pages should be written in 2.0 or 2.1 syntax
175 * When converting a page from 1.0 to 2.0/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.
176 * Avoid using HTML code and use [[XWiki Syntax>>platform:Main.XWikiSyntax]] instead
Silvia Macovei 2.1 177
178 = Preview & Save =
179
Manuel Smeria 12.4 180 * 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.
Silvia Macovei 2.1 181 * 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.
182 * If you are making small improvements make sure you check the "Is minor edit" checkbox before saving your page.
183
184 = Attachments =
185
186 * 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.
Manuel Smeria 12.4 187 * 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.
Silvia Macovei 2.1 188 * 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
189
190 = Making your page accessible on the wiki =
191
192 Once you've successfully created and edited a page it's equally important to make sure other people can reach that page as well.
193
194 * 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.
195 * You should also add links from other pages towards the document you have just created.
196
197 = Moving a page =
198
Vincent Massol 17.3 199 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.
Silvia Macovei 4.1 200
201 = Start contributing =
202
Thomas Mortagne 17.1 203 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