This is the second Friday I have been at ForgeRock. A week already. Time flies when you are having fun.
This week, among other things, I have looked at what is needed in terms of documentation. Thanks to Sun for creating and now Oracle for hosting old documentation, some of which still applies. Thanks to ForgeRock for hosting mailing lists and wikis. Thanks to web search engines that index the full text of it all. But is that really what you mean by documentation?
In a way, yes. Open source software could hardly be taken up so quickly around the world if we all had to wait for somebody to write documentation. No wonder when you boot up a new install of Ubuntu one of the first things you see is the Firefox icon, whose default page is a Google search.
Ideally we would never have to read docs. We would each have in-person, interactive support from local gurus, but they remain in short supply. Searching the web is different from asking somebody that you know knows. With everything indexed full text, the signal can get drowned out by the noise.
A good bit of the information out there is perishable as well. What was true for version 9.5.3 may no longer be the case for version 10. Healthy projects evolve actively. So should the documentation. The more frequent the updates, however, the more likely we are to introduce errors.
We clearly need both freshness and accuracy. Also, we want enough instructions and references to use all software features, in other words completeness. Let’s call this body of work core docs. Core docs thus cover all the features, track the code closely, and change in a manner that is under control. Core docs contain version information so you know whether you are reading about version 9.5.3 or version 10. If we do core docs right, then readers learn they can trust the content. Core docs become what everyone means by documentation.
The source for these core docs should live right alongside the rest of the project code. Of course at least part of the reference, like Javadoc, already does reside with the code. Keeping all the core doc source in the same repository as the rest of the code makes it straightforward to handle versioning, to use the same controls and tracking we have for features and bugs, and to build along with the project binaries. For now, I’ve been playing with docbkx-tools to process books in the core docs. Looks promising. More on that later.