Difference between revisions of "Documentation/Labs/DocumentationImprovments"

From Slicer Wiki
Jump to: navigation, search
Line 4: Line 4:
  
  
== Websites ==
 
  
=== slicer.org ===
+
== Experiments ==
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1967 1967]: Improve "slicer.org" page - Easier access to build / download / contribute</s>
 
  
=== download.slicer.org ===
+
=== User manual with GitBook ===
  
* <s>[http://www.na-mic.org/Bug/view.php?id=1966 1966]: Add disclaimer associated with 32bit on download.slicer.org</s>
+
See https://www.gitbook.com/
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1991 1991]: Cosmetics for the slicer download page</s>
 
  
== Mediawiki: wiki.slicer.org ==
+
* 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/
  
{{remark|green|Issue reports and feature requests can be listed using this link: <br>http://tinyurl.com/zzssdfb}}
+
=== Improved Wiki User Documentation ===
 
 
=== Infrastructure ===
 
 
 
 
 
* [http://www.na-mic.org/Bug/view.php?id=2971 2971]: Install MetaTags extension
 
** Would be great to try it. Note that dependent extension [https://www.mediawiki.org/wiki/Extension:StubManager StubManager] is not maintained anymore
 
 
 
* [http://www.na-mic.org/Bug/view.php?id=1543 1543]: Install CategoryTree extension
 
* [http://www.na-mic.org/Bug/view.php?id=2190 2190]: Fix graphviz installation on Slicer wiki
 
* [http://www.na-mic.org/Bug/view.php?id=2170 2170]: Install extension SyntaxHighlight_GeSHi on Slicer wiki
 
 
 
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=2272 2272]: Simplfy the first screen of the Slicer documentation page</s>
 
 
 
* [http://www.na-mic.org/Bug/view.php?id=2968 2968]: Slicer wiki - Enable short url => easier configuration of robots.txt
 
 
 
* Account
 
** [http://www.na-mic.org/Bug/view.php?id=4216 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
 
** [http://www.na-mic.org/Bug/view.php?id=4215 4215]: Notify Slicer core developers when an account is created
 
 
 
* Improved UI
 
** [http://www.na-mic.org/Bug/view.php?id=4214 4214]: Wiki: Add support for vectorial fonts
 
 
 
* YouTube extension:
 
** https://www.mediawiki.org/wiki/Extension:YouTube
 
 
 
==== Google Calendar ====
 
* Google Calendar
 
** <s>https://www.mediawiki.org/wiki/Extension:GoogleCalendar</s> 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
 
 
 
=== Improvements ===
 
 
 
==== Experiments ====
 
 
 
* 2011-11-11: Use of gitbooks to document segment-editor: https://lassoan.gitbooks.io/test-book/content/modules/segment-editor/
 
 
 
==== User documentation ====
 
  
 
This page is being developed by Hillary from Queen University with help from Andras Lasso.
 
This page is being developed by Hillary from Queen University with help from Andras Lasso.
Line 71: Line 23:
 
* [[New users]] page
 
* [[New users]] page
  
== New front page for Slicer.org ==
+
== Discussions ==
 +
 
 +
=== New front page for Slicer.org ===
  
 
* Evaluating transition of front page to a more collaborative platform. Few options:
 
* Evaluating transition of front page to a more collaborative platform. Few options:
Line 89: Line 43:
 
* Nice example of a front page for a project: https://robomongo.org/
 
* Nice example of a front page for a project: https://robomongo.org/
  
== Transition to a new platform for user/developer documentation ==
+
 
 +
== New Platform: Requirements ==
  
 
=== Expected features ===
 
=== Expected features ===
Line 139: Line 94:
 
** labels can be added to categorize 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
 
** 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 ===
 +
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1967 1967]: Improve "slicer.org" page - Easier access to build / download / contribute</s>
 +
 +
=== download.slicer.org ===
 +
 +
* <s>[http://www.na-mic.org/Bug/view.php?id=1966 1966]: Add disclaimer associated with 32bit on download.slicer.org</s>
 +
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=1991 1991]: Cosmetics for the slicer download page</s>
 +
 +
=== Mediawiki: wiki.slicer.org ===
 +
 +
{{remark|green|Issue reports and feature requests can be listed using this link: <br>http://tinyurl.com/zzssdfb}}
 +
 +
==== Infrastructure ====
 +
 +
 +
* [http://www.na-mic.org/Bug/view.php?id=2971 2971]: Install MetaTags extension
 +
** Would be great to try it. Note that dependent extension [https://www.mediawiki.org/wiki/Extension:StubManager StubManager] is not maintained anymore
 +
 +
* [http://www.na-mic.org/Bug/view.php?id=1543 1543]: Install CategoryTree extension
 +
* [http://www.na-mic.org/Bug/view.php?id=2190 2190]: Fix graphviz installation on Slicer wiki
 +
* [http://www.na-mic.org/Bug/view.php?id=2170 2170]: Install extension SyntaxHighlight_GeSHi on Slicer wiki
 +
 +
* {{done}} 2015-11-22 <s>[http://www.na-mic.org/Bug/view.php?id=2272 2272]: Simplfy the first screen of the Slicer documentation page</s>
 +
 +
* [http://www.na-mic.org/Bug/view.php?id=2968 2968]: Slicer wiki - Enable short url => easier configuration of robots.txt
 +
 +
* Account
 +
** [http://www.na-mic.org/Bug/view.php?id=4216 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
 +
** [http://www.na-mic.org/Bug/view.php?id=4215 4215]: Notify Slicer core developers when an account is created
 +
 +
* Improved UI
 +
** [http://www.na-mic.org/Bug/view.php?id=4214 4214]: Wiki: Add support for vectorial fonts
 +
 +
* YouTube extension:
 +
** https://www.mediawiki.org/wiki/Extension:YouTube
 +
 +
===== Google Calendar =====
 +
* Google Calendar
 +
** <s>https://www.mediawiki.org/wiki/Extension:GoogleCalendar</s> 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

Revision as of 00:55, 12 November 2016

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 ?


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

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