Web Development

General discussion


DOWNLOA 6 steps to better software documentation

By Mark W. Kaelin Editor ·

Documentation is often a secondary consideration during application development. How do you handle documentation? Is it an integral part your development plans or something you squeeze ;\ in as time allows at the end of project? Do you have some good advice to share on best practices for documenting software?

This conversation is currently closed to new comments.

Thread display: Collapse - | Expand +

All Comments

Collapse -

6 steps to better software documentation

by SamFelis In reply to DOWNLOAD: 6 steps to bett ...

I think this document should have another step:

*Proofread the content.*

"For example, the label Table 15-4 would represent the third table in Chapter 15."

Hmmmmm....wouldn't that be the fourth table of Chapter 15?

And how about that header on page two:

"Six ways to shoot yourself in the foot during an IT job interview"

(Now if you had added a hyperlink to that document, it might be useful, otherwise it's just a tease.)

Finally, while you ask us to "[p]lease take a minute to _drop us a line_ and tell us" how we liked the download, the hyperlink (indicated by "drop us a line") doesn't work in the PDF, nor is there any other way to do so.

And I'm supposed to trust TechRepublic with providing me with the answers?!? Yeah, right! Not this time!

Collapse -

Exactly right, Sam. TR blew it AGAIN!

by doulos8 In reply to 6 steps to better softwar ...

Another unnecessary download! This should have been an ARTICLE; no need to DOWNLOAD it. And like Sam says, the feedback link in a PDF document is worthless. COME ON, TR! Get your download act together! Readers have been telling you this for weeks.

Oh, the content of the download. Yeah, that gets forgotten because of the format. But it really left off the most important aspect of good documentation: write from the user's perspective. That's more than just considering the audience. It involves thinking of what job function they will be performing at the time the software is being used and what questions they will need the documentation to answer.

And don't (just) document the obvious. I don't know how often I have pulled down an option list in some software to find uncertain terms that needed more explanation, only to launch the help module and see field-level instructions that say "Choose A, B, C, or D" - the same list of options shown in the droplist. EXPLAIN what the options terms MEAN. What is the IMPACT of choosing A as opposed to B. Gack! The user can SEE the list. If they don't know that it's a choice field, they won't be able to find the Help either.

Related Discussions

Related Forums