TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
www.yesconsults.com
ljohnson -at- yesconsults -dot- com
