IT Employment

General discussion


What makes software documentation good

By MaryWeilage Editor ·
This week's Application Developer Management e-newsletter discusses documentation, specifically why it isn't read very often, who should write it, and what makes for good documentation.

For a closer look at effective documentation, e-newsletter author Scott Withrow suggests visiting Scott W. Ambler's insightful essay on Agile Documentation:

What do you think is the biggest hurdle in creating documentation, and how does your team overcome it? Do you usually task your developers with creating documentation, or do you bring in technical writers? What do you see as the pros and cons of both situations? Share your documentation horror and success stories with your peers.

If you aren't subscribed to our free Application Developer Management e-newsletter, click the following link to automatically sign up:

This conversation is currently closed to new comments.

Thread display: Collapse - | Expand +

All Comments

Collapse -

Just in Time

by FDIJOHN In reply to What makes software docum ...

I am currently in the process of defining how to create better documentation for "some" of our process. We run a monthly invoicing process that has to be run with a tight time frame, and must be correct. The main developer, who recently was on vaction while the application was scheduled to run, developed what he considered documentation. We had a group walkthrough of the documentation and noticed that portions of it had to be re-written. In the walktrough it became apparent that documentation was truly considered and after thought and not valubale work. As the manager, I disagreed because if none of the development satff is available to run the process --- then I have to run it. Of course, being a few levels removed from the "nuts and bolts", I definetly need operational/run instructions should this process fail to run successfully. Needless to say, we are still hashing all this out and feedback from others would be appreciated. Just a note, we use very "agile" methods for development and would like to continue with that approach for documentation too.

Collapse -

by Susan W. Gallagher In reply to Just in Time

The problems associated with tasking developers to write documentation are several... They are not writers by profession and were not selected for the job on the strength of their writing/communication skills, documentation is not their primary job so they give it short shrift at the end of the development cycle, etc. But the biggest hurdle of all is the change in perspective you throw at them. You ask them to shift gears from thinking about how to make the application work to thinking about how to use it--that's not an easy transition to make.

Technical writers come in all flavors. There are those who prefer to spend their time hand-holding the new user and there are those who like rolling up their sleeves and documenting C++ or Java code. It is entirely possible to find a technical writer who understands your application well enough to document it, whether it's a C++ API or an accounting application.

The amount of time that a technical writer will need to consult with developers in order to understand the application well enough to document it will depend on the application, of course. And generally speaking, a technical writer will require more dev time when documenting an API than a GUI. Regardless of the application being documented, the secret to effective and "agile" documentation is inter-team communication. If the technical writer is included in the planning stages and given conceptual information at the beginning of the project, there is probably no reason that the devs and writers cannot work concurrently, so that documentation is finished at approximately the same time as the code.

If, however, your definition of "agile" development forgoes the planning stages and your devs reply to the writers' request for information with, "How can I tell you what it's going to look like (or do) until I finish it?" (a reply I've heard all too often in my 21 years as a technical writer and pubs manager), then your documentation is doomed to always be the ******* child of your organization -- and that's a problem far beyond the authoritative scope of any technical writer to fix, no matter how good they are.

Collapse -

An editor makes all the difference

by jwtm In reply to What makes software docum ...

The biggest problem with documentation is indirect: Development, QA and documentation are considered as three separate activities. To get it right, a test plan should be made right at the start, the product and documentation built with the test plan in hand, and testing done on product and documentation together.

I don't believe that technical writers are all that necessary. Developers and testers can write documentation. What is needed is a good technical EDITOR to create a document plan in the first place, and to assemble, order, clean up, standardize and index the work.

Often I have found documentation to be verbose, over-stylized, and, in crucial details, vague or inaccurate. I put this down to it having been written by specialist writers rather than people who really knew the product.

So give me documentation written by developers and edited by a damn good editor.

Collapse -

Team work counts

by GordonK In reply to What makes software docum ...

The same rule applies to making documentation as it does to testing: never rely on testing that was done by the one who developed the functionality!

There is typically a project structure with assigned responsibilities in place at many IT companies.

There are following levels (if kept simple):
1) Project Manager
2) System or Business Consultant
3) Developer

Code Tester role can differ or can be "absorbed" in Consultant role depending on team size, business procedures etc.

However structure also offers answer to documenting:
The consultant knows the requirements from the client and is usually the link between a "too technical developer" and "no technical client". I've experienced in my projects (being a conultant) that the documentation is another step of testing process before the modifications can be presented to client. That is the right time to prepare documentation, because the testing - if planned properly - should also give answers to extreme situations such as troubleshooting...

Collapse -

What makes documentation bad

by bruce.miller In reply to What makes software docum ...

Too much documentation exists for the wrong reasons.

1. To protect the author. Any document that starts with a 32 page license agreement is already a failure. You may need that detail in your contract - just don't put it in the documentation.

2. So that you can claim you have documentation. This satisfies marketing checklists, but doesn't require any actual content, though.

3. Because the program is confusing. "We couldn't figure out any easy way to do what the customer wanted, so we spent 83 pages on a walk-through of the procedure they have to use."

4. Because a manual of 22 volumes looks impressive. Again, the quality of the contents doesn't matter.

And much of what was written with good intent is still bad. Scott mentioned bad writing, incomplete/inaccurate, too voluminous, hard to find things, and unexplained terms or acronyms.

I'd like to expand on "hard to find things" a bit.

5. No index or bad indexes. Documentation without an index is not useful. Indexes created by a word-processor looking up exact word matches aren't much improvement. (Can't remember how to delete a directory from the Unix command line? A good index would list that under "delete" and "directory", as well as uunder "rmdir", and maybe under "unlink". But that usually seems to be too much work).

And I'll add a last point: who is your audience? Software doing financial analysis may need a technical document describing operating system, software, and firewall environments, and details of installing and troubleshooting the product. None of this should be aimed at financial analysts. Don't put it in the same document(better yet, automate your installation, but that takes us back to point #3).

Related Discussions

Related Forums