Re: Documenting a Programming Language

Subject: Re: Documenting a Programming Language
From: "Leslie Johnson" <custcomm -at- cadvision -dot- com>
To: <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 28 Dec 1999 12:23:26 -0700

Hi Megan,

I agree with what Len mentioned - I also think that splitting the doc into a
couple of docs is the neatest (tidiest) solution - it allows you to write
for really specific audiences.

If, however, that's not an option, I'd recommend adding another chapter to
the book. Typically I've seen Getting Started chapters that tell you about
the basics of getting up and running with the app, where to find help, how
to use the documentation, etc. I'd also include a QuickStart Tutorial
chapter that contains the beginner info for that 10-15% of the audience.
This allows you to write specifically to that audience without distracting
the experienced users with "elementary" information.

Also in keeping with Len's suggestion, I'd use x-refs sprinkled throughout
the doc to refer users back to the Tutorial chapter (especially for more
advanced functions).

If you do decide to go with the QuickStart chapter, you'll need to make some
hard decisions about what should go in there - it probably can't answer ALL
the questions that your beginners need (otherwise that chapter will end up
being half the length of the rest of the book!). It can, however, hold their
hands at least part of the way and point them in the direction they need to
go, which can help them answer most of their questions.

In terms of the organization of the functions, most of the docs I've seen
and written have been organized alphabetically. I've done some usability
testing and informal surveys of programmers, and they all agree that this is
the way they like to get info, this is the way they're used to getting info,
and this is the way they expect to get info (a few of them are quite
emphatic about it).

In terms of references, my suggestions are:
1. The Microsoft Manual of Style
2. Read This First (the Sun Style Guide - an excellent tool!)
3. other Programmers Guides or Reference Guides from competitor products or
similar products - it never hurts to cherry pick some of the best ideas from
other documents that are done well!

Hope this helps, and let us know what you decided to do!
Leslie Johnson
Calgary, Alberta
YES Consultants Ltd.
ljohnson -at- yesconsults -dot- com

Previous by Author: Re: Conversion Programs
Next by Author: Fw: Documenting a Programming Language
Previous by Thread: RE: Documenting a Programming Language
Next by Thread: Re: Documenting a Programming Language

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

Sponsored Ads

Sponsored Ads