RE: Documenting a Programming Language

Subject: RE: Documenting a Programming Language
From: "Megan Golding" <megan -dot- golding -at- dvtsensors -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 3 Jan 2000 10:18:13 -0500

Thanks to everyone who responded to my post about documenting a programming
language. I got some great suggestions and wonderful references. Some of my
favorites are summarized below:

1. List functions alphabetically. (multiple posters)
2. Provide a concise listing of functions by category. (Dave Neufeld)
3. Give lots of well-commented code examples. (multiple posters)
4. Readers probably won't read the explanation paragraphs after the code,
so put the vital stuff in the comments. (Sue Gallagher)
5. Provide real-world examples. (Michael @ Rockwell)
6. Users will probably copy your real-world examples and change
them to suit their applications. (Sue Gallagher)
7. Write a Getting Started / Quick Start Chapter for novices. (Lydia Wong)
8. Include my audience assumptions in a preface & give references
so those w/out the minimum can learn more. (Lydia Wong)
9. Read Kernighan & Ritchie _The C Programming Language_. (multiple)
10.In the index, add "see also" references for commands from similar
programming languages since many users of this language
have probably used others in its class. (Geoff Lane)

I appreciate all of the great suggestions!

Megan Golding, Applications Engineer
DVT Corporation, mailto:megan -dot- golding -at- dvtsensors -dot- com

Join DVT's NEW email listserver! Send a message to
mailto:listserver -at- dvtsensors -dot- com, no subject line,
and the body should say SUBSCRIBE SMARTLIST

Previous by Author: text flows in Frame/graphics no print in pdf
Next by Author: RE: British English technical variations
Previous by Thread: re: technical writing portfolios
Next by Thread: Re: flowchart software for the Macintosh

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

Sponsored Ads

Sponsored Ads