How do you organize your Documentation?

Answer 1

As far as content goes:

• Our SDLC methodology dictates what documents we need to write.
• Our document control process dictates how we name and version the files.
• Our CM process dictates how we persist these files.

We used to store everything on our LAN, across various drives and directories, depending on what product the documentation is for, and what functional area produced it. It was a mess. So, we moved everything into SharePoint thinking it would make finding documents easier. It wasn't. Then, we tried something different:

1. All documentation for a product was organized into a single repository for that product. IOW, each product has their own document repository. We still keep everything in SharePoint, but we create a SharePoint site for each product and use a custom document library, with custom metadata, for the documents.
2. We stopped naming documents using acronyms and abbreviations. The system test plan was simply called System_Test_Plan.doc. The buisness requirements specification was called Business_Requirements_Specification.doc.
3. Rather than create folders in SharePoint, we create views to filter and group documents. Also, we find the metadata makes it easer for SharePoint to find documents when searching.
4. For admin guides and system support type docs, we use a SharePoint wiki rather than documents, which also seems to make it easier for SharePoint to find things.

The key, as you allude to above, is to make finding the documents/information easy.

Answer 2

I think it's worth having a look at Literate Programming, but teams I've worked with have had both successes and failures. Here's where I think literate programming would be helpful for you:

• Your API documentation and unit tests should be written together as a literate program.

• Your application and internal documentation for developers should be written together as a literate program.

Literate programming won't help you with your admin guide or your users' guide.

As to how you organize, it's a classic truth that the structure of your documentation reflects the structure of your organization. Or as an old professor of mine put it, as you get older you learn to ask who knows something, not what book it's in. Don't fight this phenomenon; go with it:

• Your users' guide should be the responsibility of the leader of your usability team. Or if your shop is as smelly as all that, the developer on your team who is most responsible for usability.

• Your admin guide should be the responsibility of the person who is going to get the phone call when something is wrong with the site and it needs to be fixed now.

These specifics aren't as important as the general principle: organize your documentation around the people who have the knowledge and the responsibility.

Answer 3

Administration and user guides are usually best written as Wiki pages, making sure that they are broken into clear and sensible fragments rather the "big-old-word-file" style. These sections will change frequently and will probably be written collaboratively, with a lot of how-tos written as time goes by, that nothing beats the flexibility. Using a Wiki also gives you the benefit of built-in versioning.

API documentation is a tough one. The main problem is this: When someone writes API documentation, there is a tendency to assume that whoever is going to invoke those services will read the same documentation with scrutiny. This does not happen!. People will do anything in their power to avoid the distraction of having to go and read the documentation for a call, or they will skim it, or they will look for very specific things. This will lead to problems. This is bad even when people need to just "hover" on a call in an IDE. A web-based API with web-based documentation will fair even worse.

Unfortunately, there's not much you can do against it. I've had some good initial results with a tool that alerts callers to important information in an invoked method, but that's Java specific.

What you can do to slightly improve the situation in the case of API documentation, is to very carefully read the documentation of every service/function, once very fast and once very thoroughly, and note the differences. Some but not all documentations will include "directives": things that the client really needs to know, like caveats, performance issues, side effects, unpredicted requirements, etc., that are going to come as a surprise. Make sure to make these visually distinct and very salient so that whoever does visit the API documentation does become aware of it.

Contact me directly if you want more info on this. I'll be glad ot share examples and tips.