Fw: Documenting a Programming Language

["Leslie Johnson" <custcomm -at- cadvision -dot- com>]

Forwarding this for Suzanne.
-----Original Message-----
From: Suzanne Pyle <comline -at- greennet -dot- net>
To: Leslie Johnson <custcomm -at- cadvision -dot- com>
Cc: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wednesday, December 29, 1999 7:27 AM
Subject: Re: Documenting a Programming Language


>Can anyone provide some sample references or structure for documenting a
>Web-based app using VB? This document would act like sophisticated specs,
>including high level design architect model, followed by class
descriptions,
>etc.
>
>Suzanne
>
>Leslie Johnson wrote:
>
>> 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.
>> www.yesconsults.com
>> ljohnson -at- yesconsults -dot- com
>>
>> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> Sponsored by Weisner Associates Inc., Online Information Services
>> Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based
Help.
>> More info at http://www.weisner.com/train/ or
mailto:training -at- weisner -dot- com -dot- 
>>
>> Sponsored by Rose Hill, Your Business and Career Coach.
>> "Assume Success! Live Your Passion!" Get the gist at
>> www.coachrose.com then call 503.629.4804 for details!
>>
>> ---
>> You are currently subscribed to techwr-l as: comline -at- GREENNET -dot- NET
>> To unsubscribe send a blank email to
leave-techwr-l-10051V -at- lists -dot- raycomm -dot- com
>> Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
>> http://www.raycomm.com/techwhirl/ for more resources and info.
>
>
>
>