Shared documentation system

[Shaun McCance]

On Sun, 2003-12-07 at 20:44, Murphy wrote:
> Hey'
> 
> On Sun, 07 Dec 2003 18:10:08 -0600 Shaun McCance wrote:
> 
> > This presents a problem for third-party software, though.  When ISVs
> > develop documentation for their applications, what do they do?  If they
> > have to jump through hoops to make it work with different desktops, then
> > they probably just won't bother.  They'll put it in HTML and open a
> > webbrowser.
> 
> Exactly.  I'm beginning to write documentation for the gtk-gnutella
> project.  The developers plan to separate the project into a library and
> frontend to lower the bar for new gui devs.  So we may see gnome-gnutella
> and knutella frontends based on the lib.  I want my documentation to be
> somewhat reusable in both these cases so I'll be writing in docbook-xml
> and be using the American Heritage Dictionary for spelling (never easy for
> a Canadian!)  But after that, differences in the gnome and kde styleguides
> mean that reusability will be limited depending on whether I use one, the
> other, or more likely something in between.
> 
> Arguments as to which tag should be at the top level of a user guide, etc
> are completely uninteresting to me.  I just wish to make as little
> redundant work for future maintainers and contributors of my docs as
> possible.  I was kind of hoping that a common styleguide could be
> developed so those hypothetical frontend devs would not have to mark up
> the docs all over again to get their projects included in gnome or kde. 
> However, this may be unrealistic so perhaps more adaptable help systems
> would be better.  And, after all, we can't forget whatever GnuStep, etc
> help systems there are or may be in future.

A shared style guide is a bit out of the scope of this effort.  However,
I'm sure the GNOME documentation team would be glad to work with the KDE
team on differences of writing style.  We can't always manage to agree
amongst ourselves, so I can't make any guarantees.

However, when in doubt, the best course of action is nearly always to
follow the Chicago Manual of Style.  Just about everybody's style guide
references that and makes tweaks, mostly for terminology (and, in the
case of the GNOME Style Guide, mostly for terminology relating to the
desktop, such as using 'folder' instead of 'directory').

Anything we can do to make it easier for third-party software (that is,
any software not tied to the desktop) to have quality documentation
should be given serious consideration.

--
Shaun