Documentation/Labs/DocumentationImprovments

This page keeps track of possible improvement related to the Slicer documentation infrastructure.

Experiments

User manual with GitBook

See https://www.gitbook.com/

• Segment-editor: https://lassoan.gitbooks.io/test-book/content/modules/segment-editor/
• SliceTracker: https://slicerprostate.gitbooks.io/slicetracker-user_manual/
• DCMQI: https://fedorov.gitbooks.io/dcmqi/content/v/gitbook/

Improved Wiki User Documentation

This page is being developed by Hillary from Queen University with help from Andras Lasso.

It is based on this mock-up and is intended to become the new Slicer landing page.

• New users page

Discussions

New front page for Slicer.org

• Evaluating transition of front page to a more collaborative platform. Few options:
  • Mediawiki Visual editor for front page
  • GitHub based static pages. Experiment stored here

• Current workflow:
  • Update are performed by Marianna

• What is the role of the front page ?
  • Easy to digest introduction to help decide with they would like to move forward
  • Appealing, well designed, "modern" looking
  • Page we need to "proud of" .. it show case all the great work done in the backend.
  • Well integrated with search engine (SEO). This is also coupled with user/developer documentation.
  • Given new user guidance ?

• Nice example of a front page for a project: https://robomongo.org/

New Platform: Requirements

Expected features

• Common
  • Analytics
  • Searchable
  • Integrated with C++ and python documentation generator
  • Hackable
  • Easily editable by reader with review process
  • Embed images
  • Embed python and c++ example
  • Link to original documentation for Qt, VTK, ITK, SimpleITK, python
  • Up/Down vote by user ?
  • Collect feedback ?
  • versioning history
  • authentication integrated with commonly used services (google, github,...)
  • prominent visibility of the Slicer web/doc resources on google (related issue: http://www.na-mic.org/Bug/view.php?id=3938)
  • Check and report dead links

• User
  • Tutorials
  • User Guide

• For developer
  • Cookbook
  • Reference API

Options

• gitbook:

• doxygen:

• sphinx:

• sphinx + readthedocs:

• sphinx + readthedocs + doxygen:

• mediawiki:

• user feedback: https://hypothes.is

• FAQ: dedicated github repo as done here: https://github.com/ipfs/faq ? Benefits:
  • search is potentially easier
  • easy to insert images and format content
  • users can vote on FAQ entries
  • labels can be added to categorize entries
  • github API can be used (I am assuming!) to pull this and render a web-page, after the FAQ entry has been worked on and finalized by the community

Current platform: Issues and features

slicer.org

• 2015-11-22 1967: Improve "slicer.org" page - Easier access to build / download / contribute

download.slicer.org

• 1966: Add disclaimer associated with 32bit on download.slicer.org
• 2015-11-22 1991: Cosmetics for the slicer download page

Mediawiki: wiki.slicer.org

1. Issue reports and feature requests can be listed using this link:
   http://tinyurl.com/zzssdfb

Infrastructure

• 2971: Install MetaTags extension
  • Would be great to try it. Note that dependent extension StubManager is not maintained anymore

• 1543: Install CategoryTree extension
• 2190: Fix graphviz installation on Slicer wiki
• 2170: Install extension SyntaxHighlight_GeSHi on Slicer wiki

• 2015-11-22 2272: Simplfy the first screen of the Slicer documentation page

• 2968: Slicer wiki - Enable short url => easier configuration of robots.txt

• Account
  • 4216: Wiki: Notify Slicer core developers

• Variables extension:
  • https://www.mediawiki.org/wiki/Extension:Variables
  • http://slicer-devel.65872.n3.nabble.com/Re-slicer-users-slicer-na-mic-web-stuff-upgraded-some-things-broken-this-morning-tp4035767p4035777.html

• Analytics
  • 4215: Notify Slicer core developers when an account is created

• Improved UI
  • 4214: Wiki: Add support for vectorial fonts

• YouTube extension:
  • https://www.mediawiki.org/wiki/Extension:YouTube

Google Calendar

• Google Calendar
  • https://www.mediawiki.org/wiki/Extension:GoogleCalendar This extension has not been maintained in some time, and no longer supports recent releases of MediaWik
  • Instead the following extension could be installed: https://www.mediawiki.org/wiki/Extension:Widgets

• Widgets extension:
  • https://www.mediawiki.org/wiki/Extension:Widgets
  • http://slicer-devel.65872.n3.nabble.com/Re-slicer-users-slicer-na-mic-web-stuff-upgraded-some-things-broken-this-morning-tp4035767p4035778.html