Documentation/Labs/DocumentationImprovments

From Slicer Wiki
Revision as of 00:44, 12 November 2016 by JChris.FillionR (talk | contribs)
Jump to: navigation, search
Home < Documentation < Labs < DocumentationImprovments

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

Experiments

Websites

slicer.org

  • Check.svg 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
  • Check.svg 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
  • Check.svg 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
  • Analytics
    • 4215: Notify Slicer core developers when an account is created
  • Improved UI
    • 4214: Wiki: Add support for vectorial fonts

Google Calendar

Improvements

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

Transition to a new platform for user/developer documentation

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:
  • 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