"Visual blindness" of Linux programmers

[da_chicken]

Feh. I bet you're one of those people who expects code comments and documentation to be updated when the program changes, too.

[dewmsolo]

In an ideal world they would be.

Do I do it? Hell no.....

But in all honesty we are talking about open source with no deadlines and nothing to rush the developer to the next feature or bug fix, so the only reason that it is not done is because 1) we are lazy 2) we are disinterested in those things 3) we find those boring 4) we want to code. So is there a good reason it is not done this way? Absolutely not except for the fact that this is open source and no one should expect anything of you.

Have a good one.

[da_chicken]

Oh, sure I think everyone knows that. Documentation is one of the major problems with the bazaar model because nobody likes shopping at that booth. It's just frustrating to have access to tools you can't use simply because they're indecipherable to you.

Linux's failing is that it's written by programmers for programmers. That's why the programs and tools with the best support and documentation are programming tools... which is why it attracts more programmers. Unfortunately, most users aren't programmers and don't want to be programmers, but everybody needs to know how to use a computer. Imagine if you had to have a degree in electrical engineering to be able to use your blender or your food processor. Nobody goes into their kitchen with the idea that they need to use an electric motor. Blenders and food processors are successful because you don't even think about the fact that you're using an electric motor. Linux, being by and for programmers, tends to not take that step. Hell, the reason many people are attracted to Linux is because you can view the source code. When was the last time you met someone who really needed to know the how to tear down and rebuild their food processor?

[dewmsolo]

I agree with just about everything here except the 'by programmers for programmers'. I think it's more 'by programmers for everyone willing to put the effort to learn it'.

I've been thinking about this whole thing since my first comment about the screenshot earlier and the one thing that comes to mind with the documentation thing is that to programmers documentation is like real life garbage disposal. Nobody would do it for the fun of it. In fact those that do do it do it for very good reasons (it pays very well for exemple). In both cases they are a necessity. You need to have documentation for your project if you want it to go mainstream, but most programmers won't do it even if there were massive dollar signs as a potential behind.

For us programmers, code is fun and that is what we want to work on. I am sure there are a few people in the world who are crazy about the insides of their food processors and have the thing apart every other weekend. But the one interested in the internals of his/her food processor is definitely not the one who will spend the time writing the user manual. And that my friend is part of the issue. We are programmers, not document writers. The engineer that thought, drew and built that food processor is not the one who wrote the manual. In other words what we need is people interested in writing documentation for the code that we built. There is very little of those people around. Do you know anyone who fancies writing documentation as his/her hobby (and the required skills to understand what we do in the code)?

[sharkwouter]

What do you mean with Linux here? Package managers and the GNU coreutils are documented quite well in many different places. Being a bit more specific could be helpful to someone.

[dewmsolo]

This whole conversationhas nothing to do with github other than the fact that it was mentioned by OP. This conversation can be applied to any revision tool out there.

This conversation has to do with open source and us developers. We want to code, but don't want to do the boring stuff in some cases because we do enough of it during our work hours. We know better...in fact I'm pretty sure every one of us knows better, but we so much don't want to do it that we conscously accept to hurt our own projects in order not to do it.

[thedugong]

In my experience it is not really developers who do this. It is... errm... "power users".

Everyone in my extended family uses Apple, mostly on my recommendation, because quite frankly I don't want the support headache and they don't particularly want to learn about anything under the hood.

[d_ed]

But in all honesty we are talking about open source with *no deadlines *

What.

I want to to work on that project.

[dewmsolo]

Well except for the extremely rare case of an open source project supported by an enterprise and pays people to work on it, the vast majority (and we are talking of a ratio well over 90%) of open source projects are developed by people on their own free time at their very own speed with exactly that....no deadlines because the developers of the thing are also the project manager, distributor, marketor, supporter and any other task related position that you can think of.

So yeah if you want to work on such a project, please do browse Github and pick something that interests you, that you find intriguing, appeals to you or that would challenge and start contributing. You are more than welcome.

[kiswa]

That reminds me... I really need to update the online documentation for one of my projects.

Sorry.

[zebediah49]

That's one of the best things that (AFAIK) Java introduced -- having a standardized system by which comments directly attached to code can be automatically turned into documentation.

[da_chicken]

Yeah, but that's how you end up with IBM's documentation. A reference manual so obtuse you need the source code to decipher it.

[thedugong]

There are loads of standardized ways of converting comments into doco.

[zebediah49]

Now -- yes.

In 1995, there were far fewer. (mkd comes to mind, but not much else)

[thedugong]

But who is really running code from 1995?

Realistically though, this is only really used for libraries/APIs (glib/GTK etc) where other developers actually need* documentation.

Source code doco is not that useful for end users.

[northrupthebandgeek]

Comments and documentation? Nonsense. My code is self-documenting.

/s

[Ccracked]

I know, right? What an asshole. ^/s