Re: visually describing command syntax ?

Subject: Re: visually describing command syntax ?
From: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
To: "TechWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 17 Nov 2011 14:50:26 -0800

I donât have any ideas right off, so I thought Iâd ask to see if anyone had
suggestions and particularly anything online to point to as a non-traditional
way to document command syntax?

I have done some more surfing, so I thought I'd share in case anyone else is interested:

1. Iâve seen these âbubbleâ diagrams before, http://download.oracle.com/docs/cd/B28928_01/doc/server.103/b28925/sqcmd.htm#BABIGHFB, although I have to admit that they generally confuse me more than clarify anything.

2. This oneâs not particularly visual, but I think itâs likely easier to follow than the complex <placeholder> formatting method: http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/index.jsp?topic=/com.ibm.pcomm.doc/books/html/emulator_reference14.htm (scroll down to Figure 1).

3. Similar to (2), but a bit more visual aspect to it: http://robert.wsi.edu.pl/awk/tutorial_1d.html.

4. Not useful to me now, but an interesting academic perspective: http://www.soi.city.ac.uk/~sjm/hicss01.pdf and http://ieeexplore.ieee.org/xpl/freeabs_all.jsp?arnumber=6062260.

5. An alternative syntax method (but one that Iâve always found confusing and so I wouldnât recommend it): BNF form, http://www.dataip.co.uk/Reference/BNF.php.

6. I saw several tabular formats that might be useful, but they'd work best in landscape pages instead of portrait and I'm not sure that people will like the mix of portrait/landscape.

7. Just like thereâs a way to diagram sentences in the grammatical sense, perhaps I could adapt that to the CLI commands? So far in life Iâve found diagramming sentences to be rather mysterious, but Sister Bernadetteâs Barking Dog: The Quirky History and Lost Art of Diagramming Sentences, http://www.amazon.com/Sister-Bernadettes-Barking-Dog-Diagramming/dp/0156034433/ref=sr_1_1?s=books&ie=UTF8&qid=1321566167&sr=1-1, has long had me intriguedâ

So there are some ideas out there, but nothing that really pops in a visual way (like the wonderful visual thesaurus: http://www.visualthesaurus.com/).

-Monique

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

Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com

---
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
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -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

References:
visually describing command syntax ?: From: Monique Semp

Previous by Author: visually describing command syntax ?
Next by Author: Re: Laws Requiring User Documentation
Previous by Thread: Re: visually describing command syntax ?
Next by Thread: describing command syntax using video


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads