CVSNT, Eclipse, and some lessons in OpenSource
I had the most difficult time getting eclipse 3.0.1 to work with the current CVSNT build CVSNT 2.0.58d. The knot has been finally unravelled and what I found, more importantly how I found out, seem to be a glimpse of how OpenSource and by extension any evoliving (and hence good quality) software matures.
The findings can answer the following comments fears regarding OpenSource software
- There is not much help available on your product
- Unlike a product from a large company I can not get support when I need it
- Quality is not there
How did I get into CVS
A few months ago I have worked on a project where the team was using eclipse and CVS. It worked beautifully. The whole synchronization and merging process is awsome. So last week I was establishing a brand new project and wanted to use the same tools. So I downloaded eclipse 3.0.1 and the latest CVSNT which is at build 2.0.58d.
Ran into two problems. Eclipse complains about repository path prefixes. I temporarily resolved it by specifying the drive letter and the full path. Although awkward that worked. Then I can't see anything in the HEAD or the Version or the Branches.
A search on Google yielded the difficulty of CVS and Eclipse integration issues. Apparently only a portion of the CVS interface is standardized. For example if you ask CVS for a list of modules in a repository, the syntax for "asking" is standard but not the syntax for the "answer". So the tools like Eclipse will have to mine this metadata from the messages that comes back from the cvs server.
Now you can see how difficult and flaky the integration can be between the tools. And it is. I have spend two days tracking this issue. You can read about this journey here as part of my notes on CVS. You can also find answers here on how you can make Eclipse 3.0.1 work with CVSNT 2.0.58d build. You can also find out what to do if a future release breaks.
Finally I ran into a thread of discussion that took place in the eclipse bug reporting system. This communication took place between the main developers of the eclipse plugin and CVSNT. It is a treasure trove of information and is essentiall for this collaboration to work.
The end result of that discussion was that a new tab called compatibility was introduced in cvsnt and a new build posted with in a week. With this new tab you can make CVSNT compatible to the eclipse version. You can also read about this solution at the link above I have suggested along with links to the other discussions I have mentioned.
Communication is the key to effectively work with an OpenSource product
The key to a great software product is how well the developer is connected to the user. We need to remove the barriers between developers and users to communicate with each other. If something is not working for a user who else is in a better position to answer than the developer.
Having this access to the developer instills a greater confidence in the product. Recently I had to work with a multimillion dollar product. After three rounds of global round table meetings I still couldn't get past the sales people to get my questions answered. You can not search on Google for the product manuals because they are behind locked doors in formats only their tools can read. Compare that to an OpenSource product where on a webpage, without even logging in, you can post a question and a developer gets to see that question.
As a user of an OpenSource product, one should cultivate these channels of communication to get the best out of that product. As a developer you should cultivate these channels of communication to ensure you are accessible and the users questions are answered as soon as possible.
The best advice I can give to a user of an OpenSource product is get hold of the developers emails or the webpages that they monitor and make your questions visible to them. Send them a direct email or post them to their web logs. Track them down.
One way communication channels and the OpenSource
A user gets to know about a product through the following sources
- Architecture manuals
- User guides
- Refernce guides
- Release notes
These are the hardest to establish for an OpenSource product due to the lack of resources and also due to the frequency of builds and enhancements. For example in case of CVSNT there is a PDF guide and a MicrosoftWord users guide. But you can't find any of this information as those documents are hard to produce and usually lag in functionality by months if not years. In a quick moving project manuals can hardly keep up with the reality.
Modern channels of communication
- Wiki like websites
- Mailing lists
- Web based Bug reporting
- Direct email
A website backed by a content management system or a WIKI is probably the best option for OpenSource developers to disseminate information quickly and interactively where appropriate. For example I manage the documentation for my OpenSource product Aspire/J2EE using a similar scheme.
Mailing lists are quite effective for an established product like Tomcat or Java where they have gained substantial acceptance and relatively stable. The problem with mailing lists for the early stages of an OpenSource product is their need to subscribe and unsubscribe and then monitor the emails.
For CVSNT/Eclipse I found my answers through their bug reporting system got exposed by Google. This can be a very effective tool if the bugs can be organized and visible as topics as opposed to a one line searchable database. And also the ability to open a new bug or a topic with out much fanfare
More than often you can send an email directly to the developers about the issues. You may get back atleast where to post or send your questions to get quick answers.
IOH: Inverse of Help
Usually as a user you monitor a products website for help about that product. In my mind there are cases where the inverse of that relationship works quite well, especially for Beta sites. In this idea a user creates a set of web logs or a web site focussed on activities involving the product in question. Then the product developer will monitor this site or weblog and actively answers their questions.
This also works in a teacher/group-of-students relationship as well. Where a class of students maintain an active set of weblogs that the teacher can comment on or help out with.
Ensuring the help is available
XP talks about a "Programmer's Bill of Rights". The goal there is to ensure that a programmer is productive with few barriers from their team or the environment. A good OpenSource product will ensure the "Bill of Rights" for its users by keeping the developers in constant and available contact with users.
Both commerical products and the OpenSource products can benefit from this. For Microsoft MSDN does a great job of this by allowing their developers publish content for their development users.
As far as IT is concerned they should look at their product selection using this criteria. If they were to do that a substantial number of products won't make the grade. Microsoft, through its MSDN is a rare exception. Java, through its JDK API documentation is another case in point. IBM had partially done this before with their redbooks.
Topic centric help vs Document/Book centric help
The key to provide this level of help is not to hire professional writers or create word or pdf documents. The key lies in online publishing where the documentation and help can be developed incrementally, a paragraph at a time if needed. The supporting tools should take these nuggets and give the semblance of a unified documentation.
what I have found out is that it is lot hard harder and time consuming to create a table of contents driven book like help. It is lot more easier to develop the same level of detail using one topic at a time. Then eventually cross link the topics incrementally on a wiki like website. In addition a content management system may have automated tools to compose these topics into more organized sections or books. In essence the content management system will treat these documents as XML content while allowing multiple tool enabled strategies for disseminating that content in a variety of ways.
Ensuring that support is available
There is no substitute to reaching someone that can answer questions authoritatively. IT should measure how quickly their developers can reach the developers of the product for answering questions, elaborating on architecture etc. An active participation of the real developers is a great sign.
On the question of quality
Unlike the wishes and hopes of an IT organization quality does not seem to be corelated to the size of a company. I have seen some great OpenSource projects and I have seen some bad ones too. I have seen pretty bad commercial products (more often than one would like to think possible) and some good ones as well.
A good quality product is usually surrounded by good communication channels between the developers and the users. There is a constant churning taking place between the two so that the quality raises to the top. Simplicity, consistency, and Openness are also the hall marks of a good product. It is a question of usage and age before these mature.