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 Code/Why Is It So Ugly? From:Rebecca Merck <Rebecca -dot- Merck -at- ONESOFT -dot- COM> Date:Tue, 2 Mar 1999 14:52:00 -0500
Respectfully, I agree with everything Chris just said. Always a good
idea in EVERYTHING we do to make sure the information is clear and
readable.
My good news is that we CAN do that without having to a) get a
programmer to reformat code (it's their lowest priority), and b) having
to worry about busting the code and making it uncompilable. Now just
exercise good judgement and we're on our way!
I usually try to get one well-formatted code example, using good
standards for indenting and phrasing of code, and try to get the others
to look like it. And I do run the code past the programmer to make sure
I didn't accidentally bust something.
Chris, your examples are excellent. I would have made the exact same
formatting decisions you did.
