Documentation Flavor

Version 1.197 by Ecaterina Valica on 2013/03/15 13:52
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [incubator:Improvements.AppDevelopmentFlavor]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

Documentation Flavor

Community Feedback

 (7 Feb, 2013)

Objective

A Documentation Wiki is an information repository about a certain topic (product, service, etc.) 

It needs to provide means for information to be collected, organized, shared, searched and utilized.

Use Cases

UC1: Public vs. Private Content: global or certain spaces
UC5: Related pages
UC6: Focus on page contributors

Features

Collect Information

Import

Import Office Documents (Word, Excel, Ppt) and other formats (CSV, DokuWiki, TWiki, MediaWiki, etc.) into wiki pages.
Mandatory Default Extension

WYSIWYG

You can edit the wiki page in Syntax mode or WYSIWYG mode, which provides a way to create rich content with ease.
There will be a selection of macros specialized for creating content, like adding layout, adding charts, images, table of content, footnotes, etc.
Mandatory Default

Comments & Annotations

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 on published content.
Optional Default

Workflow

Workflows are used to manage page stages, assign content contributors and publish only approved content.

Content will be first created, reviewed, approved and then published, following some predefined stages like: 'draft', 'in progress', 'approved', 'published', 'archived'. 

Users are separated in levels of users from: 'viewers', 'writers / contributors', 'editors / moderators', 'admins / webmasters', etc. each with their predefined rights.
Mandatory Extension   Custom

Macros

Mandatory   Default Custom

Pages

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'.
Mandatory Default

Templates

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, XWIKI-6684
Mandatory Default Custom

Applications

Alternative to Templates. We could store the content in specialized Documentation Applications. They are using forms to add content input.
Optional Default Custom

Organize Information

Spaces

Spaces are collections of wiki pages. They have separate administration, so they can have independent rights, presentation, backups, etc.
Mandatory Default

Metadata

Optional   Extension

Hierarchy

Mandatory   Extension

Tags

Mandatory   Default

Share & Follow Information

Share by email

Optional   Default

Watchlist

Optional   Default

RSS

Optional   Default

Optional   Default

Activity Stream

Optional   Default

Mentions

Optional   Extension

Search and Navigate Information

Search

Also in the content of attachments
Mandatory Default

Tag Cloud

Mandatory   Default

Livetable

Mandatory   Default

Breadcrumb

Mandatory   Default

Tree

Mandatory   Default

Access and Utilize Information

Rights

The whole purpose of a documentation wiki is to make information accessible to the audience, while preserving the content workflow.
There will be the following groups:

'Viewers': can read articles and may leave comments;

'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;

'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;

'Admin / Webmaster': have no restrictions. writer + editor rights + ability to create/manage users, manage global settings, view reports and statistics, take backup etc.
Mandatory Default

Export

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.
We need the ability to export a single page or multiple pages.
Mandatory Default Extension

Backup & Archive

Mandatory   Default

Internationalization

Optional   Default

Comments & Ranking

Although comments 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.
Optional Default

Instance Administration

LDAP

Mandatory   Default

Skin & ColorTheme

Mandatory   Default

Horizontal Menu

Optional   Extension

Summary

 Feature  Status
Pages (History, Attachments, Document Index)   Mandatory     Default   
Spaces  Mandatory     Default   
Import  Mandatory     Default    Extension  
Export  Mandatory     Default    Extension  
Templates  Mandatory     Default     Custom
WYSIWYG  Mandatory     Default   
Macros  Mandatory     Default     Custom
Workflow  Mandatory      Extension     Custom
Applications   Optional    Default     Custom
Comments   Optional    Default   
Annotations   Optional    Default