Flavor: Documentation
Description
Documentation Flavor
Community Feedback
Objectives
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.
Short Version
The highlights of the Documentation wiki are:
- Import and Export from diverse formats
- Custom Templates in order to rapidly create new documents
- Custom Macros focused on content creation and formatting
- Workflow in order for the content to be reviewed by dedicated users
- Hierarchical navigation and organization of the content
Issues
- Publish Workflow Application and API (git)
- Select and reorganize WYSIWYG Macros
- JIRAS:
Failed to execute the [groovy] macro. Cause: [The execution of the [groovy] script macro is not allowed in [design:Macros.jiraIssues]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.
Tasks & Features
Task: 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. This way we can control the access and make sure only high quality content is visible to end-users.
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
Macros add extra functionality inside wiki pages. There are certain macro categories, from content formatting 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.).
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
Task: Organize Information
Spaces
Spaces are collections of wiki pages. They have separate administration, so they can have independent rights, presentation, backups, etc.
Spaces organize pages in 'physical' locations, accessible through URLs.
Mandatory
Default
Metadata
Add additional information on top of pages in order to provide additional layers of information and organization.
Optional
Custom
Hierarchy
Organize your content in hierarchical order by having parent-child relationships.
They organize the pages 'logically', across spaces.
Mandatory
Default
Extension
Tags
Tags can be added to pages to describe and categorize them. Can be visualized in Tag Clouds.
They organize the pages 'logically', across spaces.
Mandatory
Default
Task: 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
Custom
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
Prevent information loss by having regular backups, useful also when doing upgrades or moving from one instance to another.
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.
Mandatory
Default
Internationalization
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.
Optional
Default
Comments & Ratings
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
Task: Search & Navigate Information
Search
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.
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.
Mandatory
Default
Livetable
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.
Mandatory
Default
Breadcrumbs
Breadcrumbs display for a certain page it's parent / child relation and position in the documents hierarchy.
Mandatory
Default
Tag Cloud
The Tag 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.
Mandatory
Default
Tree
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.
Mandatory
Default
Extension
Task: Share & Follow Information
Permalink
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.
Mandatory
Default
RSS
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.).
Optional
Default
Activity Stream
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.
Is less effective on published content, since that content doesn't suffer many changes.
Optional
Default
Share by email
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.
Optional
Default
Watchlist
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.
You can specify the frequency and delay of the e-mails. Also you are automatically subscribed to pages you contributed.
Is less effective on published content, since that content doesn't suffer many changes.
Optional
Default
Send message
You can send message internally to wiki users, mentioning pages of interest, links or just content.
Optional
Default
Task: Instance Administration
Authentification
You can create your own user base and let them authenticate with XWiki credentials or you can delegate the authentification to LDAP and get their credentials from external servers.
Mandatory
Default
Presentation
Documentation skins usually have the left column utilized for navigation (hosting the Tree). Default ColorThemes are enough.
The skin could also use an optional Horizontal Menu to contain links to important sections.
Mandatory
Optional
Default
Extension
Features Summary
| Feature | Status | |||||
|---|---|---|---|---|---|---|
| Authentification | Mandatory | Default | ||||
| Pages (History, Attachments, Document Index) | Mandatory | Default | ||||
| Spaces | Mandatory | Default | ||||
| WYSIWYG | Mandatory | Default | ||||
| Backup | Mandatory | Default | ||||
| Permalink | Mandatory | Default | ||||
| Search | Mandatory | Default | ||||
| Livetable | Mandatory | Default | ||||
| Tags | Mandatory | Default | ||||
| Breadcrumbs | Mandatory | Default | ||||
| Tree | Mandatory | Default | Extension | |||
| Hierarchy | Mandatory | Default | Extension 1 | |||
| Import | Mandatory | Default 2 | Extension 3 | |||
| Export | Mandatory | Default | Extension 4 | |||
| Macros | Mandatory | Default | Custom | |||
| Templates | Mandatory | Default | Custom | |||
| Rights | Mandatory | Default | Custom | |||
| Workflow | Mandatory | Extension 5 | Custom | |||
| Presentation | Mandatory | Optional | Default | Extension 6 | ||
| Internationalization | Optional | Default | ||||
| Comments | Optional | Default | ||||
| Annotations | Optional | Default | ||||
| Activity Stream | Optional | Default | ||||
| Send message | Optional | Default | ||||
| Share by email | Optional | Default | ||||
| Watchlist | Optional | Default | ||||
| RSS | Optional | Default | ||||
| Applications | Optional | Default | Custom | |||
- ^ http://extensions.xwiki.org/xwiki/bin/view/Extension/HierarchyMacro
- ^ http://extensions.xwiki.org/xwiki/bin/view/Extension/Office+Importer+Application
- ^ http://extensions.xwiki.org/xwiki/bin/view/Extension/Batch+Import+Application
- ^ http://extensions.xwiki.org/xwiki/bin/view/Extension/MultipagePdfExport+Application+-+Space+Export
- ^ https://github.com/xwiki-contrib/workflow-publication
- ^ http://extensions.xwiki.org/xwiki/bin/view/Extension/NavigationMenuConfig
