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,, 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: (scroll down to Figure 1).

3. Similar to (2), but a bit more visual aspect to it:

4. Not useful to me now, but an interesting academic perspective: and

5. An alternative syntax method (but one that Iâve always found confusing and so I wouldnât recommend it): BNF form,

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,, 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:



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.

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

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 for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

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