An Open Source opportunity, part 1

I guess a lot of folks will disagree with me here, but I have to say this: I think that Open Source is a great way of developing great software, but some opportunities that this way of developing software are lost or underused. I will start with one thing that is close to my heart, but there is more to it, so I will try to follow up with some more stuff later.

Documentation

Yes, documentation. You know that lengthy novel you write after people numerous times has asked for obvious things that just about anyone can see if they read your code, but they don't seem to do just that. Weird isn't it, that people try to use your code to do productive stuff instead of just putting it to good use in a productive way.

Yes, we all seem to assume that the whole world are developers and that using Open Source software somehow implies that you are just another developer. Frankly, this is not so. I think that lack of documentation is the biggest flaw of most Open Source projects. Documentation seems to come as an afterthought once the deed is done, and it's contents more often than should be the case, seems to document how the code works instead of how the program is supposed to be used.

And this is even more annoying as we are all Open Source dudes, we should be able to work together to create documentation that is not just as good as commercial software but a lot better. For example, we should be able to do better cross referencing to other Open Source software documentation. And we should be able to create a structure for at least the  basic stuff of our software that should be easily recognized independent of the software we use. For example, if I include some other software package and also use autotools to build my software, then I should be able to reference the relevant documentation for those packages, so that anyone not familiar with autotools, but who still wants to use my software, should be able to find any additional docs for autotools without me copying that as part of my documentation (something I really shouldn't do anyway).

And we are a community, right? We should be able to have other than ourselves, the software authors, to comment, add use cases and create references and examples. Does a project Wiki fulfil that purpose? Nope, not in my mind, as I here look at comments and samples for the documentation itself.

What I would want to see eventually

Writing documentation is considered boring (I don't, but I assume many do), so why don't we have a way to collaborate, so as to allow those who are better at docs to provide that. Where is that website that allows me to write and collect documentation for all sorts of open source projects? That allows dynamic cross referencing? That allows users to comment and to add use cases? That allows me to generate personalized doc sets for the software I use? That has a similar structure and common sections for different software packages, when applicable (like "Installing", "Building from source", "Change log", "Reference", "Configuring", "Quick start"). A system that allows be to view are create versioned manuals (like: "Hey, I am using MySQL 5.6, I'm not interesting what came and went in version 4.7 or something like that").

A final thought: If you had never driven a car in your whole live, would a detailed instructing on how the Otto-engine works help you? Probably not. Which is not to say that a description in detail of that same engine would not be helpful in some cases, but largely not as part of describing how to use a car in real life.

For now, this is it but I will visit another pet subject of mine that we OSS folks should be better at: APIs.

/Karlsson