Flavor: Technical Documentation

Last modified by Vincent Massol on 2024/02/26 17:57

 XWiki
 Requirements
 Idea
 

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  Twitter  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

Tasks

  1. Easy to customise navigation Menu links
  2. Easy to customise Banner text + image
  3. Easy to customise Footer links + text

Notes

  1. Display edit&create actions only for register users
  2. Allow layout choice for the first page (landing or documentation style)
  3. Allow layout style for the first page (center, full-width)

Examples

Project: XWiki

Project: Apache Maven


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)

 

Tags:
    

Get Connected