software documentation

hi,

first of all:

aaarhg! I am writing this for the second (third) time, 'cause the server took a break while receiving the post...

looks like the probs are here to stay...

ok,

I am to write a software documentation for a database driven site i developed.

Points are:

Is the documentation meant for the user or for a future developer who maybe wants to extend the app? Or does it adress both of them in different sections?
I mean, I commented my code pretty well (as we all do... ), but a detailed description of interfaces and classes a.s.o. seems as necessary as a userhelp doc.


Once this question is settled, I need to find out about a standard (ISO, e.g.) for software documentations, i.e. the structure etc.

Is there anything of the sort on the web?

thanks

I doubt there is a set standard for documentation, and most definitely there is no global standards like from iso or 802 guys. You best bet would be to follow popular formats like that of how-to's or may be even rfc's.

hi,

well, this is amazing.

The documentation is a major issue in developing, isn't it? The thought that it is up to everyone themselves to come up with a good structure seems quite unbelievable. This way noone, neither customer nor chief developers or simply 'bosses' has any guarantee as to what he'll get.

On the other hand you could come up with anything and still couldn't be sure that there is not someone who wants a little something to be added.

Very fuzzy...

Separate the end user from the future programmer. That's one thing worth noting. Don't mix the two as it means that there'll be more support needed. The end user will just give up as soon as the first technical term appears.

I do a lot of documentation at work and I always keep THREE possible groups of people in mind when I write a doc for an app I develop:

1. Users
2. Unwilling developers
3. Real developers

Users need to know how to use it, without any reference to ANYTHING under the hood. That means sit there and USE it without looking at the code while you document that part.

Unwilling developers are people that may suddenly find themselves updating, maintaining, or supporting my application because I quit, was fired, got eaten by a yak, whatever. They need to have step by step instructions on how to make common updates and solve common problems with as little technical knowledge as possible.

And of course real developers need the nitty gritty details about how the machine works.

And like what binky said... if the end user is reading the documentation and needs to ask the future programmer to clarify a term or concept, your documentation failed. It's most important to make sure the end users have the best docs possible so they don't start wandering around asking questions that should have been answered in the docs to begin with.

And, finally, what AlCapone said, you can always follow a HOW-TO or rfc format if you don't want to come up with your own. It's just that different programs require different approaches to documentation so everyone needs to do their best with what they know.

thanks,

that clears the matter of adressees.

ctb, especially


was a good hint (btw, got my personal message about hypercard?)

As concerns standards, well, as Freddie Frinton said:

"I'll do my very best."

Doesn't PEAR have a "standard" on how the documentation should be written, how code should be commented, etc...?

It might be worthwhile to look into that...

---John Holmes...

Nope, don't have one of those, sorry I do, however, remember posting a gripe about learning Hypercard long ago in the c* programming forum.

However, I note that I have a PM here from an awful long time ago that I didn't notice I had Better get a response and apology out to that one!