Re: Help files

[Federico Mena Quintero <federico@xxxxxxxxxxxxx>]

Kevin Turner <acapnotic@xxxxxxxxxxxxxxxxxxxxx> writes:

> Format issue 1: DocBook or HTML?

DocBook.  It is the Right Thing(tm) and GNOME has already assembled a
nice set of tools to handle it.

I'm sure the the GIMP documentation team can use some ideas and
conventions from the GNOME documentation project.  Please feel free to
browse the nice GDP web pages.

> Format issue 2: Style guidelines.
> =================================
> 
> Everyone probably agrees that we shouldn't have a different background
> colour for every help page.  It might also be nice if there was some
> organizational consistancy from page to page.  Also, is there anything
> that shouldn't be in the help file, or should always be in seperate
> files?  For instance, should information about using the plug-in
> non-interactively not be displayed in the same file as the rest, to
> avoid exposing the user to "scary pdb stuff"?

The way GNOME documentation is organized is more or less something
like this:

	<set>
	    <title>FooApp Documentation</title>

	    <book>
		<title>FooApp User's Guide</title>
		...
	    </book>

	    <book>
		<title>FooApp Developer's Guide</title>

		<part>
		    <title>Writing Applications/Plug-ins for FooApp</title>
		    ...
		</part>

		<part>
		    <title>FooApp API Reference</title>
		    ...
		</part>
	    </book>
	</set>

The Evolution groupware suite uses this structure.  It leads to nice
results, I think.

As for the look of the final output, it is just a stylesheet issue.
The GDP has nice stylesheets both for printing and for generating
HTML.

> Egger argues, "GIMP doesn't *need* help files to run, so they can be
> distributed seperately."  

Software is not complete until it has documentation.  The
documentation must be shipped along with the GIMP's code.

(You'll also need to do that if you have automatically-generated docs
for the API reference guide).

> Why?  It's the "Who has cvs.gnome.org write-access?" song again.
> But it's only been three days since Piers (our new Help-guy)
> requested write access, so I don't feel that's a cause for alarm
> yet.

How did Piers request access?  You can always ask cvsmaster@xxxxxxxxx
and we'll take care of it.

Again, please feel free to ask the GDP team if you have questions
about how to write or ship documentation.

Good luck,

  Federico