Re: Documenting a Programming Language

["Susan W. Gallagher" <sgallagher -at- expersoft -dot- com>]

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