Note: This file has moved to notablog.
Date : Mon, 24 Apr 2000 08:57:36 -0700 (PDT)
Author : "Steven J. Owens"
Subject : Re: Writing for Programmers, Summary
Body : Shelley Hoose writes:
> Thanks to you various techwhr-lrs for your responses to my request for a
> discussion of writing for programmers.
Sorry I missed this conversation; several years back I went from
writing for programmers to being a programmer (or at least being paid
to program, which is *not* quite the same thing... I know more writers
who couldn't hack the stress of technical writing and became
programmers, than vice versa...).
> Articles by Susan Gallagher (a fellow Techwhlr -- thanks Susan):
> http://pw1.netcom.com/~gscale/susanwg/cmindware/article1.htm.
Took a quick look, very impressive articles, look dead on, also
fairly readable and appropriate for tackling a complex topic at a
quick-overview level.
In general, I advise you to learn as much about the programming
process as you can. Obviously learning to program will help, but also
read up on the non-programming aspects of the job (you may find these
easier to tackle - project management comes naturally to tech writers,
who must usually manage their own projects :-).
Professional organizations like the ACM and the IEEE, not to
mention the various industry-oriented organizations, publish a wide
variety of useful documents. I seem to recall the ACM in particular
had a voluminous set of tomes on all sorts of standard programing
topics. If you can get your company to spring for them, do so. The
programmers might be able to help you out here - they may find them
handy as well, and they'll probably respect you more for your efforts.
Check out The Jargon File (available in various incarnations
online, or as _The New Hacker's Dictionary_ from MIT Press) for light
reading that will help you appreciate the programmer's sense of humor
- particularly make sure you read the appendices, which have general
discussions of programmer natures. You should also find and bookmark
FOLDOC (the Free Online Dictionary Of Computing), which will help you
with an assortment of definitions of real computing terms.
> 3. Just what is a functional spec and what should it include?
> "Read "the Mythical Man-Month" chapter on architecture vs. implementation.
> (I haven't had a chance to do this, but will -- thanks!)
I also recommend Steve McConnel's work, _Code Complete_, which is
generally thought very highly of in the field. Nothing on functional
specs per se, but it should help.
> "Also, search the TechWr-L archives. There was a discussion about
> documenting programming languages back in December of 1999. I saved
> a lot of those posts, because they had good advice. I know there
> have been other good discussions in the past. (Look for posts from
> Michael Wing--I remember he had some excellent advice on this
> topic.)
Some of those posts in the past were by me, I snagged them and
stuck them, unedited, on my personal web site.
writings/functionalspec.txt
writings/code_comment_standards.txt
Some bits of specific advice:
1) Learn about BNF (the format that used for command syntax
descriptions by UNIX man pages and similar docs).
2) Examples, examples, examples. You can never have two many
examples. Make sure they work - run them yourself - you'd be
surprised how many programming books have code listings that *do not
work*! Make each programmer involved with the project give you three
examples; document them well. Every working programmer I've ever
talked to (including myself, in the wee hours of the night) asked for
more examples and more detailed examples. Most programmers learn by
looking at programs. Most programming is done by looking at an
example of a solution to a similar problem, and adapting from there.
3) Don't assume that your programmers are a valid representation
of your target audience. Programmers vary widely, and in fact it's
not uncommon for the programmers building a product to be of an
entirely different stripe than the programmers using a product. And
the programmers building the product don't always know it. What they
may take for granted may be black magic to the customer programmer.
Insist on having two or three valid programmer representatives on
tap for discussions and review. Typically companies run new products
through "alpha" and "beta" testing, using preferred customers who are
contractually obligated to keep the details of the new product
confidential until it's released. This would be your best place to
get a couple representative programmers. Suggest perhaps having a
review team and a mini-mailing list to discuss the documentation,
report errors or bugs, ask questions, etc.
Steven J. Owens