RE: visually describing command syntax ?

Subject: RE: visually describing command syntax ?
From: "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>, TechWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 17 Nov 2011 14:19:05 -0800

Monique Semp wrote:

> 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)?

In addition to Dossy's suggestion, I'd recommend providing examples where the placeholders have been replaced by actual values -- preferably values that your audience will find meaningful/sensible.

IME, most developers really REALLY like examples.

Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
rgcombs AT gmailDOTcom


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: Re: Punctuation-Shaped Lamps
Next by Author: RE: Document Properties Greyed Out in Acrobat Pro
Previous by Thread: Re: visually describing command syntax ?
Next by Thread: Re: visually describing command syntax ?

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

Sponsored Ads