Re: How to document a GUI with deeply nested config items

[Robert Lauriston <robert -at- lauriston -dot- com>]

To minimize maintenance overhead, I'd embed the doc content in the XML
config file using javadoc-style comments, display that in the GUI, and
write a script to extract and transform it for inclusion in the docs
so users could search for the information.

For the docs, generate unique identifiers by concatenating the nested
path to the field, e.g. frammistat-widget-ID, frammistat.widget.ID,
frammistat > widget > ID. Users could use that to navigate to the
option in the GUI.

Depending on what framework / tools the developers are using, there
may already be some provision for javadoc-style doc comments, e.g.:

http://msdn.microsoft.com/en-us/library/fzdc5d5k%28v=vs.80%29.aspx

http://vivin.net/2011/07/09/generating-api-documentation-from-xml-using-xslt/

On Tue, Aug 19, 2014 at 8:25 PM, Melanie Albrecht
<melanie -dot- albrecht -at- gmail -dot- com> wrote:
> 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.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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