Re: Documenting a Programming Language

Subject: Re: Documenting a Programming Language
From: "Susan W. Gallagher" <sgallagher -at- expersoft -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 29 Dec 1999 16:32:32 -0800

Megan Golding wrote:
>> >I am working on a document for a programming language...
>> >I need to document every detail of this language and at
>> >the same time draw attention to the more common functions.
>
I answered:
>> If you can assume anything, it's that the user doesn't want to
>> read anything, never mind the _many_ explanations of _full-length_
>> examples. <g>
>
Steven J. Owens commented:

> Aigh! No! No no no no no. I used to write programming language
>and API documentation. One thing you want *tons* of is examples.
>Explanations of the examples is a good idea...

Me again:
Okay, let me clarify! Yes, provide *lots* of examples. Comment them,
document them, explain them every which-way! But don't just
assume your users will read the brilliant text you've written to
go along with them, becaue many of them won't. What they will do --
A LOT!!! -- is find an example that does what they want to do, copy
it, change the data, and cross their fingers. <g> But, read the text???
Don't count on it. Some of them will, sure -- most won't.

It is more important to provide plenty of good, well commented
examples than it is to write the text that will combine them into
a user manual.

I'm reminded of a conversation I had with my boss, then the CTO, when
I first started at Expersoft. I didn't know C++ and he was asking me
what I was doing to learn the language. I explained that I'd bought
this book and the other... Then I said, "but I don't have to make it
work, I just have to understand the concepts." He replied, "You know,
I've done a lot in my career by just copying examples and making things
work without ever having to understand the concepts!"

I have been writing programming and API docs for eight years now. It's
an interesting and rapidly growing field.


-Sue Gallagher http://pw1.netcom.com/~gscale/susanwg/
sgallagher -at- expersoft -dot- com http://www.expersoft.com

The _Guide_ is definitive.
Reality is frequently inaccurate. --Douglas Adams




References:
Re: Documenting a Programming Language: From: Steven J. Owens

Previous by Author: Re: Documenting a Programming Language
Next by Author: OT: Screen captures without marquee
Previous by Thread: Re: Documenting a Programming Language
Next by Thread: Fw: Documenting a Programming Language


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

Sponsored Ads


Sponsored Ads