Difference between revisions of "Embedded Help"

From Inkscape Wiki
Jump to navigation Jump to search
(Added Mac OS X section)
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== From Colin ==
== Rationale ==
* [http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/ar01s08.html "Writing Context Sensitive Help (coming in GNOME-3.0)"]
Inkscape 0.44 has some great tutorials, but they alone can not replace an embedded help system like other applications have. The deficiencies are:
* I guess we should convince pygmee and Kevin to change [http://svn.sourceforge.net/viewcvs.cgi/inkscape/user_manual/trunk/ their manual] so that it fits for that purpose, whatever change is necessary.
* one cannot find help for a specific tool
* That glossary could be section and subsections of the big manual I'd say.
* tutorials don't have hyperlinks nor an index
* see [http://wiki.inkscape.org/wiki/index.php/Report_on_c%27t_article_12/2006 this review from German c't magazine] pointing out the need of some embedded documentation/help
* tutorials cannot really be searched - search is limited to the current document and doesn't jump from hit to hit, but just highlights all hits, and the user has to comb though these


== Mail from Bob Jamison ==
Therefore, we should have a "regular", embedded help system in Inkscape, in conjunction to the tutorials.
* Context-sensitive help is one thing where I think they are spot-on.  How hard would it be for us to provide "F1 Help"? If only to pop up a browser on a given html page and #anchor. (http://permalink.gmane.org/gmane.comp.graphics.inkscape.devel/16826)


== From matiphas ==
== Ideas ==
*  kind of 3 levels of needs : instant help (already existing, but not for effects/extensions :( ); than a kind of embedded glossary, and finally a big user manual
* Cedric and Kevin's [[UserManual]] would be a nice base
* yup, a short explanation text should be integrated in the inx file or the extension code and then displayed (in a tab for a dialog ?) with the effect... I don't know what would be the best display place for it
*  kind of 3 levels of needs: instant help (already existing, but not for effects/extensions :( ); then a kind of embedded glossary, and finally a big user manual
* ok, got another idea, let's start from the Inkscape terminology page. Filling it might help creating some content for an embedded help
** short explanation text should be integrated in the inx file or the extension code and then displayed (in a tab for a dialog ?) with the effect... I don't know what would be the best display place for it (status bar at least)
* The glossary could be section and subsections of the big manual, with its own menu item.
* Context-sensitive help is one thing where I think they are spot-on.  How hard would it be for us to provide "F1 Help"? If only to pop up a browser on a given html page and #anchor. (Bob Jamison in http://permalink.gmane.org/gmane.comp.graphics.inkscape.devel/16826)
* dsign is already working on a SVG rendering help system. It' in an early stage, but it works. And yes, it can be made context sensitive, provided that a way to get the current Inkscape state (in terms of user interface) be implemented.


== MacOS X ==
== Help Systems on Different Operating Systems ==
The [http://www.devworld.apple.com/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/user_help_intro/chapter_1_section_1.html  "User Assistance"] technology or environment has [http://www.stepwise.com/SpecialCoverage/WWDC2001/501.html evolved] through several major stages, but has always been based upon a restricted HTML 3.2 [http://cocoadevcentral.com/articles/000072.php markup] and a lightweight "Help Viewer". See [http://www.andymatuschak.org/articles/2005/12/18/help-with-apple-help Help on Apple Help] for a near illegible page that describes the making of the excellent help system for the pixel editor [http://www.andymatuschak.org/pages/pixen/ Pixen] (not that many Inkscapers use pixel editors). Apple provides a [http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGUsingTechnologies/chapter_8_section_13.html comprehensive account] of the Human Interface factors relating to its technology, but this may be just outside what we need to be thinking about for Inkscape right now,
=== Linux, *BSD, Other Unices ===
* Do we want to use something like [http://live.gnome.org/Yelp Yelp]?
* [http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/ The GNOME Handbook of Writing Software Documentation] - [http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/ar01s08.html "Writing Context Sensitive Help (coming in GNOME-3.0)"]
 
=== Windows ===
* Can we produce [http://en.wikipedia.org/wiki/Microsoft_Compressed_HTML_Help CHM files]?
** [http://www.kosek.cz/xml/dboscon/dbhelp/frames.html From DocBook to integrated help systems]
** [http://www.herdsoft.com/linux/themen/hlp_to_chm.html  Converting .hlp files to .chm]
** [http://xchm.sourceforge.net/ xchm], a CHM viewer
** [http://gnochm.sourceforge.net/ GnoCHM], another CHM viewer (for Gnome)
** [http://www.nongnu.org/chmspec/latest/ unofficial CHM spec]
** [http://www.speakeasy.org/%7Erussotto/chm/ CHM doc]
** http://beeblex.com/lists/index.php/php.pear.doc/7216?s=l:php.pear.doc
 
=== MacOS X ===
The [http://www.devworld.apple.com/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/user_help_intro/chapter_1_section_1.html  "User Assistance"] technology or environment has [http://www.stepwise.com/SpecialCoverage/WWDC2001/501.html evolved] through several major stages, but has always been based upon a restricted HTML 3.2 [http://cocoadevcentral.com/articles/000072.php markup] and a lightweight "Help Viewer". See [http://www.andymatuschak.org/articles/2005/12/18/help-with-apple-help Help on Apple Help] for a near illegible page that describes the making of the excellent help system for the pixel editor [http://www.andymatuschak.org/pages/pixen/ Pixen] (not that many Inkscapers use pixel editors). Apple provides a [http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGUsingTechnologies/chapter_8_section_13.html comprehensive account] of the Human Interface factors relating to its technology, but this may be just outside what we need to be thinking about for Inkscape right now.
 
* [http://chmox.sourceforge.net/ "Read your CHM documents on your Mac."] - maybe an option too


== See also ==
== See also ==
[http://www.g2meyer.com/usablehelp/items.html Usable Help] A list of just under 250 links to articles on documentation and help systems for software and consumer products.
* [http://www.g2meyer.com/usablehelp/items.html Usable Help], a list of just under 250 links to articles on documentation and help systems for software and consumer products.
* [http://wiki.inkscape.org/wiki/index.php/Report_on_c%27t_article_12/2006 Review of Inkscape 0.44 from German c't magazine] pointing out the need of some embedded documentation/help
* ScislaC has a plan to re-arrange and extend our existing tutorial system (FIXME: is there anything written down yet?)


== Open Questions ==
* do we want to use something like [http://live.gnome.org/Yelp Yelp] in *nix?
* can we produce [http://en.wikipedia.org/wiki/Microsoft_Compressed_HTML_Help CHM files] for Windows?


[[Category:Developer Documentation]]
[[Category:Developer Documentation]]

Latest revision as of 22:14, 3 July 2007

Rationale

Inkscape 0.44 has some great tutorials, but they alone can not replace an embedded help system like other applications have. The deficiencies are:

  • one cannot find help for a specific tool
  • tutorials don't have hyperlinks nor an index
  • tutorials cannot really be searched - search is limited to the current document and doesn't jump from hit to hit, but just highlights all hits, and the user has to comb though these

Therefore, we should have a "regular", embedded help system in Inkscape, in conjunction to the tutorials.

Ideas

  • Cedric and Kevin's UserManual would be a nice base
  • kind of 3 levels of needs: instant help (already existing, but not for effects/extensions :( ); then a kind of embedded glossary, and finally a big user manual
    • short explanation text should be integrated in the inx file or the extension code and then displayed (in a tab for a dialog ?) with the effect... I don't know what would be the best display place for it (status bar at least)
  • The glossary could be section and subsections of the big manual, with its own menu item.
  • Context-sensitive help is one thing where I think they are spot-on. How hard would it be for us to provide "F1 Help"? If only to pop up a browser on a given html page and #anchor. (Bob Jamison in http://permalink.gmane.org/gmane.comp.graphics.inkscape.devel/16826)
  • dsign is already working on a SVG rendering help system. It' in an early stage, but it works. And yes, it can be made context sensitive, provided that a way to get the current Inkscape state (in terms of user interface) be implemented.

Help Systems on Different Operating Systems

Linux, *BSD, Other Unices

Windows

MacOS X

The "User Assistance" technology or environment has evolved through several major stages, but has always been based upon a restricted HTML 3.2 markup and a lightweight "Help Viewer". See Help on Apple Help for a near illegible page that describes the making of the excellent help system for the pixel editor Pixen (not that many Inkscapers use pixel editors). Apple provides a comprehensive account of the Human Interface factors relating to its technology, but this may be just outside what we need to be thinking about for Inkscape right now.

See also

  • Usable Help, a list of just under 250 links to articles on documentation and help systems for software and consumer products.
  • Review of Inkscape 0.44 from German c't magazine pointing out the need of some embedded documentation/help
  • ScislaC has a plan to re-arrange and extend our existing tutorial system (FIXME: is there anything written down yet?)
Retrieved from "https://wiki.inkscape.org/wiki/index.php?title=Embedded_Help&oldid=15481"