documenting a programmable user interface

[Karen Otto <KAREN_OTTO -at- HP-SPOKANE-OM2 -dot- OM -dot- HP -dot- COM>]

Item Subject: cc:Mail Text
     We have a product which has both a manual and programmable user
     interface.
     Up to now, we have put great detail into the manual user interface,
     and provided only syntax reference railroad diagrams for the
     programming commands.

     We recognize the needs of our customers, and are busy developing new
     ways of linking the programming commands to the screens. Our customers
     need to link fields to commands, and to understand what the commands
     do.

     I though for a while our best way would be to just do it as a command
     dictionary. That is, have one entry per command, with things like:
       Command name
       Command description
       Syntax
       Program Sample
       Notes

     Because the commands map so closely to the fields on the screen, I
     think we can do better than this.
     Some ideas we are trying:
     - include syntax examples with field descriptions
     - point to the command reference from the field descriptions

     Some questions:
     1) do we need to eliminate the syntax diagrams all crowded onto a few
     pages in favor of a many paged, descriptive command reference?
     2) Is a command list (compact listing of commands), plus a command
     dictionary (see above) the most common way to go?
     3) Does anyone have a silver bullet solution?


     thanks,
     Karen o.
     karen_otto -at- hp-spokane-om2 -dot- om -dot- hp -dot- com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Post Message:	TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Get Commands:	LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "help" in body.
Unsubscribe:	LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU with "signoff TECHWR-L"
Listowner:	ejray -at- ionet -dot- net