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: Writing for Programmers, Summary From:"Steven J. Owens" <puff -at- netcom -dot- com> To:shelley -at- a-frame -dot- com Date:Mon, 24 Apr 2000 08:57:36 -0700 (PDT)
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...).
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.
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.
