Show last authors
1 {{velocity}}
2 $xwiki.ssx.use("Improvements.WebHome")
3 $xwiki.ssx.use("Standards.WebHome")
4 $xwiki.ssx.use("Improvements.DocumentationFlavor")
5 {{/velocity}}
6
7 = Documentation Flavor =
8
9 (% class="left column50 dashboardleft" %)
10 (((
11 {{toc depth="3"/}}
12 )))
13
14 (% class="dashboardright right column50" %)
15 (((
16 {{gallery}}
17 image:DocumentationHomepage.png
18 {{/gallery}}
19 )))
20
21 (% class="clearfloats" %)
22 (((
23
24 )))
25
26 == Community Feedback ==
27
28 {{info}}
29 [xwiki-devs] [Brainstorming] [Flavor] Documentation Flavor http://markmail.org/thread/cvfzvwv6dnhkimuy (25 Mar, 2013)
30 {{/info}}
31
32 (% class="left column40 dashboardleft" style="width: 27%" %)
33 (((
34 == Objectives ==
35
36 A Documentation Wiki is an information repository about a certain topic (product, service, etc.)
37
38 It needs to provide means for information to be collected, organized, shared, searched and utilized.
39
40 == Short Version ==
41
42 The highlights of the Documentation wiki are:
43
44 * [[Import>>]] and [[Export>>]] from diverse formats
45 * Custom [[Templates>>]] in order to rapidly create new documents
46 * Custom [[Macros>>]] focused on content creation and formatting
47 * [[Workflow>>]] in order for the content to be reviewed by dedicated [[users>>]]
48 * [[Hierarchical>>]] navigation and organization of the content
49
50 == Issues ==
51
52 * Publish Workflow Application and API ([[git>>https://github.com/xwiki-contrib/workflow-publication]])
53 * Select and reorganize WYSIWYG Macros
54 * JIRAS:
55 {{jiraIssues}}XWIKI-7260,
56 XWIKI-5704,
57 XE-897,
58 XWIKI-6684{{/jiraIssues}}
59 )))
60
61 (% class="dashboardright right column60" style="width: 70%" %)
62 (((
63 {{comment}}
64 //**BUC1**//: Collect Information
65 Import (Office, CSV), Create, WYSIWYG, Workflow, Templates, Applications, Comments&Annotations
66 //**BUC2**//: Organize Information
67 Spaces, Tags, Metadata
68 //**BUC3**//: Share Information
69 Share by Email, Watchlist, RSS, PermaLinks, Mentions
70 //**BUC4**//: Search and Navigate Information
71 Search (also in the content of attachments), Livetable, Tag Clouds, Breadcrumbs, Tree
72 //**BUC5**//: Publish and Utilize Information
73 Read, Permissions, Comments, Export PDF, ODT, HTML; Internationalization, Backup
74 {{/comment}}
75
76 == Tasks & Features ==
77
78 === (% class="primaryTitle" %)Task:(%%) Collect Information ===
79
80 {{container layoutStyle="columns"}}
81 (((
82 ==== Import ====
83 Import [[Office>>http://extensions.xwiki.org/xwiki/bin/view/Extension/Office+Importer+Application]] Documents (Word, [[Excel>>http://extensions.xwiki.org/xwiki/bin/view/Extension/Batch+Import+Application]], Ppt) and other formats (CSV, DokuWiki, TWiki, MediaWiki, etc.) into wiki pages.
84 {{status group='M'/}} {{status group='D'/}} {{status group='E'/}}
85
86 ==== WYSIWYG ====
87 You can edit the wiki page in Syntax mode or WYSIWYG mode, which provides a way to create rich content with ease.
88 There will be a selection of [[macros>>||anchor='HMacros']] specialized for creating content, like adding layout, adding charts, images, table of content, footnotes, etc.
89 {{status group='M'/}} {{status group='D'/}}
90
91 ==== Comments & Annotations ====
92 Collaboration and reviewing on wiki pages can be made through comments (global level) and annotations (contextual level) on unpublished content. The functionality could be disabled or [[enabled>>||anchor='HComments26Ranking']] on published content.
93 {{status group='O'/}} {{status group='D'/}}
94
95 )))
96 (((
97 ==== Workflow ====
98 [[Workflows>>https://github.com/xwiki-contrib/workflow-publication]] are used to manage page stages, assign content contributors and publish only approved content. This way we can control the access and make sure only high quality content is visible to end-users.
99
100 Content will be first created, reviewed, approved and then published, following some predefined **stages** like: //'draft'//, //'in progress'//, //'approved'//, //'published'//, //'archived'//.
101
102 Users are separated in levels of **users** from: //'viewers'//, //'writers / contributors'//, //'editors / moderators'//, //'admins / webmasters'//, etc. each with their predefined [[rights>>||anchor="HRights"]].
103 {{status group='M'/}} {{status group='E'/}} {{status group='S'/}}
104
105 ==== Macros ====
106 Macros add extra functionality inside wiki pages. There are certain macro categories, from [[content formatting>>||anchor='HWYSIWYG']] to application specific macros, that can be generally used or specific to documentation wikis (Workflow Status, Page Contributors, Related Pages, Rate content as useful etc.).
107 {{status group='M'/}} {{status group='D'/}} {{status group='S'/}}
108 )))
109 (((
110 ==== Pages ====
111 Pages are atomic entities of the wiki. They have //'Copy'//, //'Rename'//, //'Move'//, //'Delete'// functionality. Also you can manage the //'History'// (restore versions), add //Attachments// to them and manage them with //'Document Index'//.
112 {{status group='M'/}} {{status group='D'/}}
113
114 ==== Templates ====
115 We can create an empty page or use Page Templates, that contains predefined content and structure. Templates are integrated in the '//Create//' page action. See [[XE-897>>http://jira.xwiki.org/browse/XE-897]], [[XWIKI-6684>>http://jira.xwiki.org/browse/XWIKI-6684]]
116 {{status group='M'/}} {{status group='D'/}} {{status group='S'/}}
117
118 ==== Applications ====
119 Alternative to [[Templates>>||anchor="HTemplates"]]. We could store the content in specialized Documentation Applications. They are using forms to add content input.
120 {{status group='O'/}} {{status group='D'/}} {{status group='S'/}}
121 )))
122 {{/container}}
123
124
125
126 === (% class="primaryTitle" %)Task:(%%) Organize Information ===
127
128 {{container layoutStyle="columns"}}
129 (((
130 ==== Spaces ====
131 Spaces are collections of wiki pages. They have separate administration, so they can have independent rights, presentation, backups, etc.
132
133 Spaces organize pages in 'physical' locations, accessible through URLs.
134 {{status group='M'/}} {{status group='D'/}}
135
136 ==== Metadata ====
137 Add additional information on top of pages in order to provide additional layers of information and organization.
138 {{status group='O'/}} {{status group='S'/}}
139 )))
140 (((
141 ==== Hierarchy ====
142 Organize your content in hierarchical order by having parent-child relationships.
143
144 They organize the pages 'logically', across spaces.
145 {{status group='M'/}} {{status group='D'/}} {{status group='E'/}}
146 )))
147 (((
148 ==== Tags ====
149 Tags can be added to pages to describe and categorize them. Can be visualized in [[Tag Clouds>>||anchor='HTagCloud']].
150
151 They organize the pages 'logically', across spaces.
152 {{status group='M'/}} {{status group='D'/}}
153 )))
154 {{/container}}
155
156
157
158 === (% class="primaryTitle" %)Task:(%%) Access and Utilize Information ===
159
160 {{container layoutStyle="columns"}}
161 (((
162 ==== Rights ====
163 The whole purpose of a documentation wiki is to make information accessible to the audience, while preserving the content [[workflow>>||anchor="HWorkflow"]].
164 There will be the following groups:
165
166 //'Viewers'//: can read articles and may leave comments;
167
168 //'Writer / Contributor'//: adds new articles, makes changes to his own articles, attach files to his own articles and all the new articles created by a writer are not published to the documentation unless they are moderated/approved by either an Editor or Admins;
169
170 //'Editor / Moderator'//: writer rights + create new articles, make changes to existing articles, create/manage categories, delete articles (but cannot access the ?Trash? for permanent deletion), create/manage tags;
171
172 //'Admin / Webmaster'//: have no restrictions. writer + editor rights + ability to create/manage users, manage global settings, view reports and statistics, take backup etc.
173 {{status group='M'/}} {{status group='D'/}} {{status group='S'/}}
174
175 )))
176 (((
177 ==== Export ====
178 The wiki displays the information as an online web page, but various output formats are needed for a wider audience. This should cover formats like XML, PDF, Word, ODT, Excel, CSV, HTML, DocBook XML, Dita XML, etc. but also the ability to print the content.
179 We need the ability to export a single page or [[multiple pages>>http://extensions.xwiki.org/xwiki/bin/view/Extension/MultipagePdfExport+Application+-+Space+Export]].
180 {{status group='M'/}} {{status group='D'/}} {{status group='E'/}}
181
182 ==== Backup & Archive ====
183 Prevent information loss by having regular backups, useful also when doing upgrades or moving from one instance to another.
184
185 Archive functionality could be added to pages and spaces when they switch from 'Draft' to 'Publish' stage or when a new version for a documentation page replaces the older published version.
186 {{status group='M'/}} {{status group='D'/}}
187
188 )))
189 (((
190 ==== Internationalization ====
191 There are over 21 language available for your wiki, depending on the audience you need to handle. Also you can add your own translation or improve a current one.
192 {{status group='O'/}} {{status group='D'/}}
193
194 ==== Comments & Ratings ====
195 Although [[comments>>||anchor='HComments26Annotations']] can be used in the content creation and validation process, they could also be enabled for the published content, in order to get feedback and rating from the viewers.
196 {{status group='O'/}} {{status group='D'/}}
197 )))
198 {{/container}}
199
200
201
202 === (% class="primaryTitle" %)Task:(%%) Search & Navigate Information ===
203
204 {{container layoutStyle="columns"}}
205 (((
206 ==== Search ====
207 Search for content inside pages, comments, objects and also in the content of attachments. You can restrict your search results by using filters based on location, content type, modification date, author, etc.
208
209 Also the Search Suggest feature rapidly displays the top matches for a certain query and highlights documents name, document content, attachment content and user names.
210 {{status group='M'/}} {{status group='D'/}}
211
212 )))
213 (((
214 ==== Livetable ====
215 Livetables allow filtering of pages that share structured data. You can view multiple details on a certain page, like name, location, author, modification date, images, etc. Pages selection can be done for an entire space, wiki, tag, author, etc.
216 {{status group='M'/}} {{status group='D'/}}
217
218 ==== Breadcrumbs ====
219 Breadcrumbs display for a certain page it's parent / child relation and position in the documents hierarchy.
220 {{status group='M'/}} {{status group='D'/}}
221 )))
222 (((
223 ==== Tag Cloud ====
224 The [[Tag>>||anchor='HTags']] Cloud display all the tags found for a certain use case (in a certain space, or by a certain author) and lets you browse pages that are labeled with the same tag.
225 {{status group='M'/}} {{status group='D'/}}
226
227 ==== Tree ====
228 You can visualize the hierarchy of pages starting from a specific parent or location. We need a tree integrated in the left panels, used for navigation.
229 {{status group='M'/}} {{status group='D'/}} {{status group='E'/}}
230 )))
231 {{/container}}
232
233
234
235 === (% class="primaryTitle" %)Task:(%%) Share & Follow Information ===
236
237 {{container layoutStyle="columns"}}
238 (((
239 ==== Permalink ====
240 Have permanent links to point to your content. This mechanism is mandatory and built in for pages, but you can also link to comments, sections of content, attachments, users, certain version of the content, etc.
241 {{status group='M'/}} {{status group='D'/}}
242
243 ==== RSS ====
244 Changes and activity notifications are also available in RSS format in order to stay up to date. There are some pre-defined feeds that you can subscribe (activity stream, blog, etc.).
245 {{status group='O'/}} {{status group='D'/}}
246 )))
247 (((
248 ==== Activity Stream ====
249 Activity Stream lets you monitor the activity on pages, comments, attachments, by seing new, edited, deleted content. The Activity Stream is an useful tool in the creation process by highlighting additions and contributions.
250
251 Is less effective on published content, since that content doesn't suffer many changes.
252 {{status group='O'/}} {{status group='D'/}}
253
254 ==== Share by email ====
255 You can share pages through mail or with other users. The pages can be just linked or embedded inside the message, containing comments and attachments.
256 {{status group='O'/}} {{status group='D'/}}
257 )))
258 (((
259 ==== Watchlist ====
260 Get informed about wiki modifications with the watch feature. You will be notified by email of any changes to the pages: edit, delete content, comments, attachments, etc.
261
262 You can specify the frequency and delay of the e-mails. Also you are automatically subscribed to pages you contributed.
263
264 Is less effective on published content, since that content doesn't suffer many changes.
265 {{status group='O'/}} {{status group='D'/}}
266
267 ==== Send message ====
268 You can send message internally to wiki users, mentioning pages of interest, links or just content.
269 {{status group='O'/}} {{status group='D'/}}
270 )))
271 {{/container}}
272
273
274
275 === (% class="primaryTitle" %)Task:(%%) Instance Administration ===
276
277 {{container layoutStyle="columns"}}
278 (((
279 ==== Authentification ====
280 You can create your own user base and let them authenticate with XWiki credentials or you can delegate the authentification to [[LDAP>>http://extensions.xwiki.org/xwiki/bin/view/Extension/LDAP+Application]] and get their credentials from external servers.
281 {{status group='M'/}} {{status group='D'/}}
282 )))
283 (((
284 ==== Presentation ====
285 Documentation skins usually have the left column utilized for navigation (hosting the Tree). Default ColorThemes are enough.
286
287 The skin could also use an optional [[Horizontal Menu>>http://extensions.xwiki.org/xwiki/bin/view/Extension/NavigationMenuConfig]] to contain links to important sections.
288 {{status group='M'/}} {{status group='O'/}} {{status group='D'/}} {{status group='E'/}}
289 )))
290 (((
291
292 )))
293 {{/container}}
294
295 (% class="clearfloats" %)
296 (((
297
298 )))
299 )))
300
301 (% class="clearfloats" %)
302 (((
303
304 )))
305
306
307 == Features Summary ==
308
309 (% class="statusTable" %)
310 |= Feature |=(% colspan="6" width="40%" %) Status
311 |[[Authentification>>||anchor="HAuthentification"]] |{{status group="M"/}} | |{{status group="D"/}} | | |\\
312 |[[Pages>>||anchor="HPages"]] (History, Attachments, Document Index) |{{status group="M"/}} | |{{status group="D"/}} | | |\\
313 |[[Spaces>>||anchor="HSpaces"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
314 |[[WYSIWYG>>||anchor="HWYSIWYG"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
315 |[[Backup>>||anchor="HBackup26Archive"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
316 |[[Permalink>>||anchor="HPermalink"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
317 |[[Search>>||anchor="HSearch"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
318 |[[Livetable>>||anchor="HLivetable"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
319 |[[Tags>>||anchor="HTags"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
320 |[[Breadcrumbs>>||anchor="HBreadcrumbs"]]|{{status group="M"/}} | |{{status group="D"/}} | | |\\
321 |[[Tree>>||anchor="HTree"]]|{{status group="M"/}} | |{{status group="D"/}} |{{status group="E"/}} | |\\
322 |[[Hierarchy>>||anchor="HHierarchy"]]|{{status group="M"/}} | |{{status group="D"/}} |{{status group="E"/}}{{footnote}}http://extensions.xwiki.org/xwiki/bin/view/Extension/HierarchyMacro{{/footnote}}| |\\
323 |[[Import>>||anchor="HImport"]]|{{status group="M"/}} | |{{status group="D"/}}{{footnote}}http://extensions.xwiki.org/xwiki/bin/view/Extension/Office+Importer+Application{{/footnote}} |{{status group="E"/}}{{footnote}}http://extensions.xwiki.org/xwiki/bin/view/Extension/Batch+Import+Application{{/footnote}} | |\\
324 |[[Export>>||anchor="HExport"]]|{{status group="M"/}} | |{{status group="D"/}} |{{status group="E"/}}{{footnote}}http://extensions.xwiki.org/xwiki/bin/view/Extension/MultipagePdfExport+Application+-+Space+Export{{/footnote}}| |\\
325 |[[Macros>>||anchor="HMacros"]]|{{status group="M"/}} | |{{status group="D"/}} | |{{status group="S"/}} |\\
326 |[[Templates>>||anchor="HTemplates"]]|{{status group="M"/}} | |{{status group="D"/}} | |{{status group="S"/}} |\\
327 |[[Rights>>||anchor="HRights"]]|{{status group="M"/}} | |{{status group="D"/}} | |{{status group="S"/}} |\\
328 |[[Workflow>>||anchor="HWorkflow"]]|{{status group="M"/}} | | |{{status group="E"/}}{{footnote}}https://github.com/xwiki-contrib/workflow-publication{{/footnote}}|{{status group="S"/}} |\\
329 |[[Presentation>>||anchor="HPresentation"]]|{{status group="M"/}}|{{status group="O"/}} |{{status group="D"/}} |{{status group="E"/}}{{footnote}}http://extensions.xwiki.org/xwiki/bin/view/Extension/NavigationMenuConfig{{/footnote}}| |\\
330 |[[Internationalization>>||anchor="HInternationalization"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
331 |[[Comments>>||anchor="HComments26Annotations"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
332 |[[Annotations>>||anchor="HComments26Annotations"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
333 |[[Activity Stream>>||anchor="HActivityStream"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
334 |[[Send message>>||anchor="HSendmessage"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
335 |[[Share by email>>||anchor="HSharebyemail"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
336 |[[Watchlist>>||anchor="HWatchlist"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
337 |[[RSS>>||anchor="HRSS"]]| |{{status group="O"/}} |{{status group="D"/}} | | |\\
338 |[[Applications>>||anchor="HApplications"]]| |{{status group="O"/}} |{{status group="D"/}} | |{{status group="S"/}} |
339
340 {{putFootnotes/}}

Get Connected