[Gllug] Open source == 'Popular Computing'

Alain Williams addw at phcomp.co.uk
Mon Apr 20 11:11:21 UTC 2009

On Mon, Apr 20, 2009 at 11:47:44AM +0100, James Laver wrote:
> On 20 Apr 2009, at 11:45, Joel Bernstein wrote:
> > On 20 Apr 2009, at 11:40, Alain Williams wrote:
> >> Info was one of these great ideas that just did not work.
> >
> > I suspect it might work better if you live in emacs to begin with? I
> > don't and have never really got on with it.
> >
> > /joel
> I *do* live in emacs and I still don't get on with it.


Documentation is one of the areas that annoys me most with open source stuff:


* The number of programs for which there is *no* man page at all.

* The number of programs that will not generate a meaningful usage message.
  Some tell you what the options are, sort of, but don't have a line or two at the top
  telling what the hell the thing is about in the first place - or use some
  obscure acronym.

* Out of date/wrong. Someone updated the programs and could not be bothered to
  update the docs.

This is all basic stuff. I am not talking about well written & comprehensive
documentation - I am talking about a few lines scraped together.

Yes: we do need well written & comprehensive stuff, but we aren't reaching first base.

I have released some programs open source, it often takes as long to write the
documentation as it did the code. But without the documentation the code is useless.

Then you look at the code: acres of code with virtually no comments - other than the GPL copyright.

It isn't that hard, but it does require that the programmer realise that there do exist other
people in the world - then people can't see the inside of his head.


Alain Williams
Linux/GNU Consultant - Mail systems, Web sites, Networking, Programmer, IT Lecturer.
+44 (0) 787 668 0256  http://www.phcomp.co.uk/
Parliament Hill Computers Ltd. Registration Information: http://www.phcomp.co.uk/contact.php
Past chairman of UKUUG: http://www.ukuug.org/
#include <std_disclaimer.h>
Gllug mailing list  -  Gllug at gllug.org.uk

More information about the GLLUG mailing list