Flavor: Technical Documentation
Blog Posts:
Description
Purpose
Create a flavor that allows easy creation of XWiki instances suited for writing technical documentation.
The instance will contain documentation for a specific project, from user guides to API references and FAQs. Pages will contain from simple content like images and code samples, to macros and applications targeted towards software development.
Can be used by people wanting to provide support for a particular software or by developers that maintain and develop one.
Allows easy:
- customisation of the appearance (colors, logo, header);
- customisation of navigation links from menu and footer;
- and also allows creating a landing page with a specific layout in addition to the documentation layout.
Just like any XWiki instance, it is very extensible by supporting applications related to software development like Release Notes, IRC Archives, GitHub Stats, Dashboards, etc.
Features
Basic | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Features | Pages Basic: Create, Edit, etc. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Versioning, History, Changes, Blame | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Export to PDF, XAR, Backup | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Administration, Rights (Open / Public Website) + Private / Internal Pages | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Search + Quick Search | Livetable | Profile | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Macros | Box, Info, etc. | Code, Tree, Gallery, Toc, etc. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Advanced / Thematic / Optional | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Configuration | Custom Domain | Subdomains | HTTPS support | Hosting | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Templates | Roadmap | Download, Installation | Contribute | 404 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Macros | Jira | Chart | Google (YouTube, Maps, Calendar) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Apps | FAQ, Forum | Blog | Dashboard | Stats | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Release Notes | GitHub Stats | Flash messages | Version archive | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Extra | Workflow | Internationalization | Spam Protection | IRC Bot | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Integrations | GitHub | Markdown | Google Analytics |
Skin: Dove
Content
Tasks
- Easy to customise navigation Menu links
- Easy to customise Banner text + image
- Easy to customise Footer links + text
Notes
- Display edit&create actions only for register users
- Allow layout choice for the first page (landing or documentation style)
- Allow layout style for the first page (center, full-width)
Examples
Project: XWiki
Content
Project: Apache Maven
Content
Implementation
Differences
- Flavor
- Removed Help, Sandbox application
- Remove all macros or applications not needed by the use case
- Marked as hidden some XWiki pages
- Skin
- Different fonts for text and code
- Hidden tags, last modified, created area
- Removal of #docextra from WebPreferences
- Display viewers in the "More actions" menu even if #docextra is hidden
- New save buttons layout
- Menu
- Fixed top menu
- Menu integrated inside primary navbar (#menuview)
- Removal of avatar and notification UIX
- Style adjustments (text-transform, etc.)
- Drawer should simply entries
- Panels
- WebPreferences using a left only panels layout + large panels width
- Navigation panel using document reference to display children
- Panel header style adjustments
- Edit mode using large panels width
- Adjust width for large panels width on big resolutions
- Custom
- Header is displayed only on Main.WebHome (custom velocity + ssx; careful on edit mode)
Issues
- Needing UIX points or default pages that are included in the Header, Menu, Footer area
- Providing default templates for Header, Menu and Footer
- Provide Administration area to modify the Header, Menu and Footer
- Provide the font also locally or make a call to Google Fonts for online instances
- Menu: reordering pages (non alphabetical order)
Additional
- Provide alternative templates for Header
- Provide 3 tested ColorThemes for the skin (see how to separate from the default ones - maybe not install them by default)