4 December 2009

FOSS Documentation.

I have just read this article on documentation or rather the lack of it in the Linux and FOSS communities.

To be honest I am currently about two weeks behind in my feed reading so have missed most of the comments and articles that seem to have been written on this. However, this is an area of Free Software where I think a lot can be done.

I have to say that in the 7 years I have been using Linux it's only really since I moved to Arch that I have appreciated having a good source or help and documentation. In my early days of using Linux I found the quality of help was very hit and miss. Some forums (i.e. where brilliant and people would really try and help and point me in the right direction. Others leave one line comments which may make sense when you know the answer but which do nothing for those who know nothing. There is some documentation for some applications but it's usually out of date and non complete.

At the end of the day this problem is not FOSS specific. Having been a developer for nearly 10 years I have to say that it is incredibly rare for documentation to be written. The application I currently work on is a highly configurable web application with one source tree and each client having it's own configuration. We are two years into this application and have only a couple of documents covering a couple of points of the system. I am currently fighting to get them to at least add c# xml documentation comments so I can try and build some documentation using Doxygen. In previous applications I have been paid to work on we have not had any documentation written and I have fought the same battle. So this is obviously a problem that is to do with coders who seem to think that a good coder will get how it works by reading the code and users will just get it because it is obvious. However, not all users find all applications obvious.

In personal applications I have written that other people will use I have included at least a simple HTML page with a description of each menu and tool bar action and with lots of screen dumps. It works. I don't get any questions.... bug reports? yes! Errors? Oh yeah....! Questions about how to use it ... rarely.

This is an area where Linux and FOSS could take the lead. If we could start to build good quality documentation which meant my mum could install Linux and get up and running with little hassle more people would start using it. Windows applications have a standard help format and I think Linux could do with the same. My mum does not want to read man pages. Why would she? Big colourful html help files with lots of screen shots, kept up to date. Would that really be hard to do?

However, a major point that should be remembered is that, as with coders, people who contribute to FOSS do so in their own time and for little or no reward. Perhaps it is time that some of the big Linux vendors (Oracle, IBM, SuSe) ramp up the documentation effort.

No comments: