Gary Schnabl schrieb:
Martina Waller wrote:
Hi all ,
in order to create a style guide for our help files I am currently
sifting through the existing help files. I have set up a wiki page
where I am collecting irregularities of the help style:
http://wiki.services.openoffice.org/wiki/Documentation/Help_Style_Guide
If you know of further inconsistencies, please add them to the wiki
page or let me know. Any comments are welcome, too.
Without my yet going through it, I might suggest (in the event it's
not covered) that a normal text paragraph be the first element
(assuming XML) after every subhead.
For now we do that only after the first level heading. Sublevels are
often like for example "Switching off the Word Completion" and then
follow the steps 1., 2. and so on. A normal text paragraph after the
heading would be "To switch off the word completion do the following:"
but that would only repeat the heading and inflate the help texts. But I
will reconsider that when I am creating the style guide.
Also, only use the next lower-level subhead when there are at least
two of such children subheads for each parent. Otherwise, the
exposition in the documentation should be rewritten in order to
comply. This "rule" is typically found in many corporate style guides.
You are absolutely right. I already mentioned that on the wiki page.
Another item: make sure that the documentation always agrees with the
GUI component name or text. Even if the GUI is in error, use the
erroneous GUI data in the documentation until the GUI component gets
rectified. There have been instances where there were as many as three
difference versions of GUI components in the past: one for the GUI
implementation, another for the online help, and yet another form in
the OOo documentation guide.
This is already one of our unwritten guidelines. If you know the terms
that are different in the GUI and the application help please give me a
hint.
Thanks
Martina
--
[EMAIL PROTECTED] - Technical Writer
StarOffice - Sun Microsystems, Inc. - Hamburg, Germany
http://www.sun.com/staroffice
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
