documentation

[mcnewsxp]

can anyone provide a good example or template for the documenting your
applications? the audience would be other developers and subject
matter experts. in this case the applications would not be large
systems, but might be used in a large system. so only the details
that pertain the the app would be required.
i realize no one likes to do do it and most structured programmers
believe that their code is documention enough. but sometimes clients
require it.

 

[Willem van Rumpt]

can anyone provide a good example or template for the documenting your
applications? the audience would be other developers and subject
matter experts. in this case the applications would not be large
systems, but might be used in a large system. so only the details
that pertain the the app would be required.
i realize no one likes to do do it and most structured programmers
believe that their code is documention enough. but sometimes clients
require it.

I'm not completely sure what kind of documentation you're looking for:
Is it documenting the application, or is it documenting a library
interface? Do you want functional documentation for end users of an
application (i.e. : "click filemenu -> click open -> select file") or
technical documentation for programmers consuming your library (i.e. :
document constraints, exceptions, input, output, and what not).

In either case, I'm don't know of a magic one-fits-all template.

If it's developers you're targeting, then all the usual requirements pop
up (description, preconditions, postconditions, parameters, exceptions),
and your best bet is using something like GhostDoc that takes care of
some of the tedious work of documenting your library. But they will only
document a snapshot of the current state. Keeping it up to date and
adjusting it will still be manual work.

 

[Registered User]

can anyone provide a good example or template for the documenting your
applications? the audience would be other developers and subject
matter experts. in this case the applications would not be large
systems, but might be used in a large system. so only the details
that pertain the the app would be required.
i realize no one likes to do do it and most structured programmers
believe that their code is documention enough. but sometimes clients
require it.

Test driven design could be a suitable solution. A suite of tests
documents what the software can & can't do and acts as sample code
showing how to interact with API.

<http://msdn.microsoft.com/en-us/library/aa730844(v=vs.80).aspx>
<http://msdn.microsoft.com/en-us/magazine/cc163982.aspx>

regards
A.G.

 

[Arne Vajhøj]

can anyone provide a good example or template for the documenting your
applications? the audience would be other developers and subject
matter experts. in this case the applications would not be large
systems, but might be used in a large system. so only the details
that pertain the the app would be required.
i realize no one likes to do do it and most structured programmers
believe that their code is documention enough. but sometimes clients
require it.

Documentation is part of software delivery.

For an application you need for external users:
- installation guide
- operations guide

For a library you need for external users:
- API docs generated from XML comments
- users guide

For internal users you need:
- architecture and design docs with UML diagrams

I don't have any templates that I can share.

Arne