visually describing command syntax ?

Subject: 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 12:57:20 -0800

Hello, writers,

(And sorry if you get this multiple times; I am asking this on several listservs.)

Iâm documenting the syntax for lots of commands that have fairly complex and inconsistent syntax: some have key-value pairs (and so I document the âvalueâ portion as a placeholder indicated with italic code font within angle brackets), some have both required and optional parameters, sometimes the parameters are denoted by switches instead of key-value pairs â in short, all the usual inconsistencies of a big set of commands thatâs grown over time under lots of developers.

People are rightly concerned that the syntax descriptions (especially the placeholders) arenât that easy to follow, and Iâve been asked whether thereâs perhaps some visual way to make the connection between the <placeholder> and its explanation (which is in a long bulleted âWhereâ list that follows the command syntax line)?

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?


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


Previous by Author: Re: FrameMaker: Imported Text: Removing Overrides
Next by Author: Re: visually describing command syntax ?
Previous by Thread: Survey question on TechWhirl- What do you find most stressful as a technical writer?
Next by Thread: Re: visually describing command syntax ?

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

Sponsored Ads