There are many changes on the horizon for rPath Documentation.
One of the things that team docs here has known for a while is that the rPath wiki is a fantastic tool to leverage for documentation. It’s quick. It’s easy. It allows engineers to contribute directly to the wiki. It allows community members to contribute to to the wiki.
We’ve also known for a while that this tool has a major caveat…and that is that versioned documentation is costly. For example, if we had say version 1.0 documentation of a project at wiki.rpath.com/v1/productname and version 2.0 came out, we’d have to maintain 2 separate documents with the same information in two different URI’s and 2 different name spaces. With each addition of namespace and project version, updates would be more costly and time consuming.
It’s also a bad thing that a user can search the wiki…and have the possibility of getting results from versions that they are not using…possibly information and behavior of products that no longer applies.
So how do we plan on combating this? There are a couple of phases of plans that we’ve been thinking about. The first of these is to move all product related guides (Administrative, User) offline into docbook format (pdf, html). We’ve begun testing this idea already.
This buys us the ability to keep versioned documentation separate from the wiki which empowers customers by giving them only the documentation they need and not requiring them to wade through search results to get the documentation they need.
This also is good for the community. Why? Because community docs will remain on the wiki and product documentation will be separated from it 🙂 This means that documentation on using open source tools like Conary and working with rBuilder Online will be separate from rPath products making things easier to find and easier to contribute to.
The next phase of the plan after separating product specific documentation is to provide a central repository for those offline docs. This is further down the road and will only take place if product documentation has been moved offline. When this phase hits, there will be a handy website that serves as a central repository for all documentation, whether product based or community based. Currently, there are no plans to move community documentation from the wiki (Conary, rBuilder Online, rMake).
So, those are some of the updates we’ve been talking about doing. Nothing is set in concrete but we’re continuing to stay busy by keeping the information readily available to both community and customer 🙂
