Software Enviroment Documentation Checklist

Question

Hi,

I work for a insurance company. We have our own development department made-up of almost 150 people plus some providers (outsourcing and custom made apps pretty much). In our company my team have made what we call non-fucntional logic libraries. That is, software libraries to handle things that are horizontal to all the development teams in our department, e.g. Security, Webservices, Logging, Messaging and so on. Most or these tools are either made from scratch or adaptation of a de-facto standard. For example our logger is an appender based on Log4J that also saves the logging messages into a DB. We also define what libraries to use in the application, for example which framework for webservices to use. We use pretty much JavaEE and Oracle AS in all our organization (with some Websphere Application servers).

Much of these projects have their architecure documented (use cases, UML diagrams, etc) and generally the generated documentation are available. Now what we have seen is that for users sometimes is difficult to use the the libraries we provide and the are constantly asking question or they simply don't use them.

So we are planning to generate a more friendly documentation for them, so my question is: What are the best practices or the checklist that sofware documenation should have?

Something comes to my mind:

1. API Reference guide
2. Quick start Tutorial
3. API Generated Documentation.
4. Must be searchable
5. Web Acess

What else should it have? Also, based in your experience what is the best way to mantain (keep it up-to-date) and publish this type of documentation?

Thank you!

Answer 1

Keep your documentation in version control too.

Make sure on every page it has a version number so you know where your user has been reading from.

Get a CI server going and push documentation to a LIVE documentation site upon updates.

Do documentation reviews like you would code reviews.

Dog-food it :)

Kindness,

Dan