General Question

marla's avatar

how detailed should software documentation be?

Asked by marla (27points) July 3rd, 2007

I'm a project manager of a software documentation project (however have never created such myself). Is it reasonable that executing a function could take 40 or 50 steps?

Observing members: 0 Composing members: 0

3 Answers

ben's avatar

This seems like two questions, so let me take a stab at each. As far as how detailed documentation should be, I'd say the more the merrier. Obviously, at some point you can get too verbose, but the opposite problem (lack of documentation) is much much more common and much harder to rectify. So: very detailed.
As far as functions with "40 or 50 steps" you probably have to be more specific about the context. For maintenance, smaller, more encapsulated functions are generally better, but there are no hard and fast rules. In the right place, a 40-step function could be fine.... but it should still have proper documentation and comments. Does this answer your question?

marla's avatar

Thanks so much for responding. You say, "maintenance, smaller, more encapsulated functions are generally better,". Does this mean it's easier to update the documentaiton if the descriptions or funcitons are chunked in to small pieces? Do you do software documentation for a living? Just curious.
Thanks again!

andrew's avatar

@marla: Are you managing a project that writes the documentation? I'm the code that writes the documentation 40 or 50 steps or is the code that you're documenting 40 or 50 steps?

What stage of development are you at? Is the code done and you're documenting formally? Adjusting standards amongst the developers to come up with consistent documentation? Is this internal or external documentation?

Answer this question




to answer.

This question is in the General Section. Responses must be helpful and on-topic.

Your answer will be saved while you login or join.

Have a question? Ask Fluther!

What do you know more about?
Knowledge Networking @ Fluther