Most mISV's don't need to worry about these aspects. When you're only one person, a great big file or a whiteboard or any number of other tools can probably fit your needs. But once you add a second person or a second project/product, it gets that much more complicated. Now your mnemonics and half-notes aren't as valuable… in fact, some may be a liability.
Hello, I'm Keith and I'm an information addict. I don't seek to catalog all the world's information. I don't even seek to collect it. My goal is to take what I have and make it useful.
That may sound odd but think about it… most information has a few specific properties:
- The most important/expensive information is usually the most time-sensitive;
- It isn't useful if you don't know how to find it;
- Different people will look for the information in different ways depending on the questions they need answered;
Towards this goal, I've been experimenting with different wiki structures – exclusively on MediaWiki – and how to use them to fulfill those requirements. Here are the results of a year of tweaking and refinement.
First, links, links, links. Although you may know the specific terms/references and expect everyone else to know them, they won't. In fact, depending on who you are and who is reading the documentation, the disconnect could be fundamental and begin with the first words. Therefore when you mention an odd or complex term the first time, link to it. This applies doubly to acronyms and project/organization-specific terms.
Second, you can never over-categorize. This may sound silly, but remember you're not working with a physical object… putting the item in one category doesn't prevent you from putting it in as many as you want. For example, when I roll out a new dotProject customer, I add categories representing the version of dotProject, the AddOn Modules they're using, and even identifying if they have customizations. By clicking a single link, I can easily group the systems across a variety of aspects. If I have an update to the Project Importer, I know exactly who needs the upgrade. It doesn't get much easier.
But a category isn't only a logical grouping, it can also serve as a physical grouping. It's trivial creating categories based on any arbitrary grouping – it was barely five minutes to create a list of BarCampDC presentations – but you could group the server/cluster where the applications are running. In no time at all, you can cross-categorize the information to the point where a Sales Guy could look to see everyone using Product X without any knowledge of the servers while a System Admin could determine everything running on Server A without any knowledge of Product X. When you have a server/application problem or you're pushing to make a sale, this could be the information that saves the day.
Finally, once you begin using a tool like a wiki, you must ensure that everything goes into it. If a Sales Guy asks how a particular feature works, add the answer to the wiki and send a link. If you discover a particularly useful query or feature, add it to the wiki and send a link to those who need to know. The key is to make the wiki second nature… both for initial searching and for capturing the informaiton afterwards and (re-)categorizing things as needed. Yes, it will take a while, but the information will get better and better and interruptions will become more and more rare. There are two phrases to learn here: "It's on the wiki!" and "Put it on the wiki!".
Your documentation has the opportunity to be a resource to everyone from the Sales Guy to the Jr. Developer to most senior System Admin. The keys are to collect it in a managable way and then use terms that each of the groups recognize and segment the information in meaningful ways… but doing this at the beginning is difficult at best and impossible in reality. You don't know everything about your organization or how your people think. But now you and they have the opportunity to add information and express the way they think… and make something useful for themselves and others.
Remember that all of the major wiki systems out there have version control. Even if you completely miscategorize or write something wrong, it can easily be corrected or rolled back as necessary.