Documentation

Sorry. I hate to whine with my first post but......

Why is it that we in the open source community seem to have a deep rooted fear of documentation?

Ive just downloaded and installed Project log. and now cant figure out how to set it up, what its actually supposed to do nor what the various options are.

I will persevere a little while longer but quite frankly, im getting fed up with developers who seem to think that all software is completely self explanatory and that documentation is for idiots.

Having worked in IT and been a SW dev for almost 25 years, it still astounds me that so many of us cant even write a simple explanation of what an app is supposed to do or what the features are.

End of rant....


Tony

Please read this-- extensions.thethinkery.net/index.php?opt...ticle&id=4&Itemid=16

Hi. Thanks for the reply, but that is EXACTLY what i was talking about. I dont want to beat you up, but that is NOT documentation. Its a half finished walk through that tells me nothing. (I had already read it.)

1) Its incomplete - It was possibly written before the advent of some features i.e categories so it made it impossible to follow as you cant enter a project without a category - Or at least i couldn't.)

2) By following the walk through i was still in the dark about most of the fields and their purpose. (Not coming from a project management background i don't have that inbuilt knowledge.)

3) When i got to the end, i still had no idea what the software did or how. It was only through trial and error that i realised that I had to be logged in at the front end to see anything. Sure it may be "obvious" now that i know, but it wasn't at first.

This isn't directed solely at you, but expresses my growing frustration with Open Source development in general. We as a community seem to have fallen into a mind set of "If you cant figure it out you shouldn't use it." or we fall back on that old chestnut, the "user forum" where we hope that frustrated users will eventually write enough tips and workarounds to qualify as documentation.

I do realise that you are releasing this as free software, and do appreciate the work you have obviously put in. But im trying to get more of us to think about the docs.

And that really is the end of the rant.

Fair enough. I should know better, my first job in software was tech writing!

However-- while you have a good point, it's also true that we released this for free, in the hopes that it might help others. Typically, in open source projects, you have lots of outside collaboration. And to that end, you're very welcome to help us provide better documentation!

Thanks for the comments, and especially for making your point courteously.