Ever since 2001 I remember hearing the same thing about xCAT: “The documentation needs improvement”, “There is a steep learning curve”. Back in those days the quick xCAT-mini-howto was a great way to get going. The problem is that it left out a lot of the important details like service nodes, offloading tftp servers, etc. For most questions you really just had to read the code to figure out the solution. But it was a great way to start.
Later there came a redbook and that was great but now its far too outdated to be helpful. For the most part, we kept writing a bunch of mini howtos for individual implementations. Looking back this is something we should have taken more serious. I think the project would be much farther along had we done something.
When xCAT 2 was created in 2007 there was a discussion about what to do about the documentation. The decision (which I don’t agree with) was to write the docs in OpenOffice and then create PDFs out of them. Others (me) thought it would be nice just to create a general wiki but the other camp didn’t like that you couldn’t make PDFs out of them. (Yes, I know you can, but its not so obvious on SourceForge how to do it). So the xCAT documentation was created in Open Office and distributed with the xCAT rpms. You can see it all here. In addition, Another IBM redbook was written (and then quickly outdated) and we in the field tried updating the xCAT wiki but the camp was divided and this probably caused more confusion than good.
So now we have a problem. Its the problem we’ve always had. There is a lot of documentation, but its all over the place. There is no single place to get all the information. In fact, we even made a document to help you find the right document. Its called the ‘Top Document’. I’m sorry, but that is just pathetic.
For any configurable software to really succeed there needs to be easy to follow, well thought-out, quality documentation system. I think many developers feel that documentation is beneath them: “The documentation is in the code”. They are too busy adding new features to worry about the common mundane problems of telling people what they did. This kind of thinking limits the install base. I am frankly more concerned that nobody has taken this very seriously before. It is the number one thing I hear from xCAT users: Make a good doc!
So I started thinking about what kind of documentation I would like for xCAT. I started writing a book and thought about publishing it but I could never find the time to finish it. In addition things changed quickly and I didn’t make it a priority. In addition, how would I distribute it? How would I update it since it would be obsoleted so quickly? So I made a list of requirements:
– It must be maintainable very quickly. Wiki’s are great because people can edit them right away. Firing up an Open Office doc, editing, then converting to PDF, then checking back in is too archaic and takes too much time. An agile development environment needs to have an agile documentation environment. So any docs are out. Some wiki’s are too restrictive. I don’t like the one on sourceforge because I like a project to have its own look and feel.
– It must be social. People should be able to comment on the documentation. Readers can add lots of good information and tips for other readers that would save us a lot of work. (They can also call us out if things don’t make sense.) The PHP and MySQL sites were great examples of this where people would give tips on how to use certain functions. Often times I would find the answers for what I was looking for in the readers comments.
– It must have a consistent format and be easy to follow. The problem with the PDF approach is that as it grew, nobody would want to combine them and so we had a proliferation of PDF documents. (Hence the reason for the Top Document) We need a way to be reorganize, add, expand and be very flexible. In addition we need to have a consistent format and be easy on the eyes 🙂
So I looked at documentation projects I liked. I already mentioned PHP and MySQL. jQuery was another one that I thought was excellent. They are all web based. This makes it better: Now people can just use a search engine to find the answers they need! Something you can not get in a static document living in a repository. But what about the people installing xCAT that don’t have access to internet? Fine make it so we have a PDF that can be generated on the fly.
I also looked at commercial products. This just seemed kind of wrong to do for an open source project. They don’t lend themselves to collaboration and I just didn’t get a good vibe about them. Plus, I hate opening up other applications. I want to do it all through the browser!
So web based authoring seemed the way to go based on all I saw. But what platform? I liked the navigation of Red Hat’s documentation but I didn’t want to be forced to use Linux nor DocBook. Too much work to update. Plus, there was no commenting system. Drupal and others seemed like a bit of an overkill as did Word Press. I would have to spend more time learning how to customize them than just writing something from scratch. At http://xcat.sf.net. We don’t have a lot of control over that environment because its hosted by sourceforge. And logging in takes forever and is quite frustrating to me. So I had to find another place to host it.
So here is my solution: http://sumavi.com is a rails application. We made it so that we could extend the Sumavisor (which is also a rails application) for our future evil plans. Why not just create a quick documentation model? I sat down for 3 days and wrote one out, tried to stylize it and even integrated Disqus (a la jQuery) to have a commenting system.
The system still has a few problems, but was easier to write than I thought. (yes, you elite programmers are shocked that it took me 3 days to do, but hey, I had to deploy it as well as do my day job) I then started adding the content of my book and so far I am very pleased. The navigation is easier, I can change things around quicker and I have to say it is very agile.
I am hopeful in the coming days that we will solve the xCAT Documentation problem. I am hoping that more people will use xCAT because they will see how easy it is to use. I am hoping that people will be able to use search engines to find answers to xCAT problems. The mailing list has been a great help to this, but its time to get more modern. I am hoping to have something mostly done by mid October.
For any feature-rich software like xCAT, it is imperative to have a good documentation system. It can be one of the things that sets you apart from the crowd. Its frustrating not being able to get things work. I’ve downloaded many packages and disgarded them after not being able to get it to run. Its also important to use the collective wisdom of the community. But the community needs an initial structure to build on.
Take a look at the docs we’ve started and let me know your thoughts. Like I said, we’re looking to have something usable by mid October. You can look at them here.
Comments are closed.