RE: visually describing command syntax ?

["Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>]

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
303-223-5111
------
rgcombs AT gmailDOTcom
303-903-6372
------





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

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