Re: visually describing command syntax ?
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
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads