How to document a GUI with deeply nested config items

[Melanie Albrecht <melanie -dot- albrecht -at- gmail -dot- com>]

Hello everyone

I need to document how to configure a complex software product.

*Background:*
I'm writing in English for sys admins, some of whom are Indonesian and have
English as a second language. We will not be translating the documentation.
The point of this book is to reduce the support overhead (currently
massive... 1-3 months on site per customer!) so that we can sell this
product "off-the-shelf".

*The GUI:*
The configuration is (not so) secretly stored as an XML file. Mostly, the
administrator responsible for configuring the product deals with a GUI that
represents the XML config in a fairly basic manner. They should not need to
go to the underlying XML file for any config task.

The config GUI represents the XML directly, which means that config items
are nested deeply. Some config items are decorated with genuinely helpful
descriptions, but they are in small green text.

Because items are nested, their names are not unique. For example, there
are many fields named ID.

*My problem:*
I need to tell my readers how each config item works, and what type of info
to enter. I'm having trouble thinking of a good way to format this
information. My thoughts so far:

   - *Table: *Nice clear formatting, but not easy to represent nesting.
   Also does not handle the many tables that appear in the actual GUI.
   Sub-tables, anyone?
   - *Screenshot with callouts: *Some GUI pages are really long, so
   screenshots would have to be chopped up. Hard to maintain.
   - *XML-style formatting, like this
   <http://stackoverflow.com/questions/1752588/how-to-document-the-structure-of-xml-files>:*
   Very tempting, because it's pretty obvious that this GUI is just a skin
   over an XML file. However the whole point of the GUI is to make the config
   more human-readable.
   - *GUI only: *Put no field descriptions in the doc, and beef up the
   descriptions that appear on the GUI.


What do you think?

Thanks,
Melanie

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives