Documentation/Labs/DocumentationImprovments

From Slicer Wiki
Jump to: navigation, search
Home < 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/

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.

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 ?

Improved FAQ

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

New Platform: Comparison

Proposing changes

GitBook

ReadTheDocs

Uploading Images

ReadTheDocs / GitHub

Current platform: Issues and features

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