plans for the help browser...

[Oliver George <o_george postoffice utas edu au>]

Miguel de Icaza wrote:
<snip>
> * The Help browser
> 
> Given the Bonobo wrapper for an HTML engine, write a help browser
> that renders into HTML the documents we have.
> 
> Include on it:
> 
>         1. Index for commonly used things.
>                  * info
>                  * man
>                  * Docbook pages
> 
>         2. Search function.
> 
>         3. Link to gTrouble troubleshooting system.
> 
>         4. History, favorites
> 
>         5. Provide a way to "mark" parts of the documents displayed,
>            to underline pieces of text (TkMan did this ages ago).
> 
>         6. Provide support for annotating texts (TkMan did this ages
>            ago, back on my SunOS 4.x machine).
> 
> If we can move toward using the XML-based Docbook setup, we could
> even parse SGML files directly, without having to go trouch the jade
> process.  This would put us in par with Solaris man pages (which are
> fully Docbook based these days).
> 
> Opinions, comments?
> Miguel.

I think the two hardest parts of documenting an application are, knowing
what information to include and keeping the information up to date.

To that end these are just a few feature thoughts i've always wanted
from existing help systems...

* It would be great to provide a trivial way of contributing back to the
global help system contents.  I mean i want to be able to:

  - submit a contribution (say a paragraph) without the trauma, ie. just
by hitting the edit/contribute button. 

  - make a suggestion for what I wanted to find on a particular page but
couldn't...


* A couple of specifics I'd like to see in the search function:

  - You should be able to search both globally and specifically in an
application help system.

  - There should be a trivial way of telling an application maintainer
that you were searching for a word but you didn't find the information
you were hoping for.  As an example say you wanted to search for 'mime'
in your email application to find out whether the application
implemented it fully or not.


Hope this is useful to you.  I'm interested to hear some other opinions
regarding documenting and a full help system for gnome.


Best wishes, Oliver.