Ted Leung on the air
Ted Leung on the air: Open Source, Java, Python, and ...
Ted Leung on the air: Open Source, Java, Python, and ...
Sat, 13 Sep 2003
I don't want to read your damned source code
I've titled this post the way that I think Jason should have titled
his. I'm an open source guy and I believe in the open source method of producing software. However, I believe in open source for pragmatic, not ideological reasons, and what Jason is complaining about here is one of the ways that open source needs to grow if it's really going to be successful. We are not doing a good job of making sure people don't need to have the source. One of the reasons that I'm writing a book is that there's a need for documentation, and the experience of doing the research for the book has made me much more aware of what people are facing when they try to use some of the code at the ASF.
The source code, the licensing, and the process should combine to yield a better product. There is a benefit to having the source. But we can't neglect the other stuff either.
It's hard to have an accurate perception of yourself. I know that this book project has helped me to see some areas where the ASF, at least, needs to improve.
[01:16] |
[computers/open_source] |
# |
TB |
F |
G |
8 Comments |
I see the problem as going deeper, hence the tone of my blog entry. I was afraid it might be a little too short to get the point across, but I omitted some fairly venomous passages from it in order maintain a little civility.
Maybe I'll append another paragraph to clear things up:
It's not just that open source authors are light on documentation, it's that many of them are still SMUG about it, implying there's something wrong with me if there code isn't immediately transparent to me. Granted, it used to be much worse, but it's still pretty bad. I frankly don't have the time and energy to get familiar with the code. I've got a six book backlog on my bookshelf, of three technical and three just-for-fun books. Plus all of the things I need to get done for work, four coding projects of my own, a house, a yard, and an electric keyboard that was a birthday present. All of these are collecting dust while some smartass is telling me I should just go blow 60 hours of my life memorizing his code.
Sure, these folks need to grow, but they also need to grow up.
Posted by Jason Marshall at Sat Sep 13 11:41:39 2003
Maybe I'll append another paragraph to clear things up:
It's not just that open source authors are light on documentation, it's that many of them are still SMUG about it, implying there's something wrong with me if there code isn't immediately transparent to me. Granted, it used to be much worse, but it's still pretty bad. I frankly don't have the time and energy to get familiar with the code. I've got a six book backlog on my bookshelf, of three technical and three just-for-fun books. Plus all of the things I need to get done for work, four coding projects of my own, a house, a yard, and an electric keyboard that was a birthday present. All of these are collecting dust while some smartass is telling me I should just go blow 60 hours of my life memorizing his code.
Sure, these folks need to grow, but they also need to grow up.
Posted by Jason Marshall at Sat Sep 13 11:41:39 2003
I understand your point totally. Strengths are also weaknesses, and while "developer rule" is a strength, it's also a weakness. And its not just in the documentation area. It's designing usable API's and usable configuration mechanisms, and a whole host of other things.
Part of the growing is "growing up". It is going to take some time for people to figure this out. Maybe it will take competition from within the open source community to make people realize that there's more to it than just the source.
I think that its a good thing that there's some software out there that's interesting enough to get you angry that the documentation is lousy. The question is how to get people to see this as a problem and then do something about it. Otherwise you might as well just let them play in their sandbox and hope that someone will do the job right and not charge you too much for the effort.
Posted by Ted Leung at Sat Sep 13 11:56:25 2003
Part of the growing is "growing up". It is going to take some time for people to figure this out. Maybe it will take competition from within the open source community to make people realize that there's more to it than just the source.
I think that its a good thing that there's some software out there that's interesting enough to get you angry that the documentation is lousy. The question is how to get people to see this as a problem and then do something about it. Otherwise you might as well just let them play in their sandbox and hope that someone will do the job right and not charge you too much for the effort.
Posted by Ted Leung at Sat Sep 13 11:56:25 2003
All open source projects are not created equal.
If the principal goal of the open source project's author is to scratch her own itch, and if she doesn't need documentation in order to meet that goal, why is she under an obligation to write it? Society may gain from her writing good documentation. She herself might gain if her goal switches to one of wanting community assistance on the project. But if the code alone meets her goals, then she loses by writing documentation, just as you lose by having to wade through code to read it. It's not like your time is inherently more valuable than hers, particularly if she has no earthly idea who you are or that you even exist.
Now, there are many open source projects who purport to be trying to scratch society's itches and who fail to do a reasonable job of making it easy for society: limited docs, no precompiled binaries for common platforms, no easy APIs or tutorials, etc. For those projects, your beef is understandable. But just because it's open source does not mean that there is a rule that it has to be documented well.
Posted by Mark Murphy at Sat Sep 13 12:12:25 2003
If the principal goal of the open source project's author is to scratch her own itch, and if she doesn't need documentation in order to meet that goal, why is she under an obligation to write it? Society may gain from her writing good documentation. She herself might gain if her goal switches to one of wanting community assistance on the project. But if the code alone meets her goals, then she loses by writing documentation, just as you lose by having to wade through code to read it. It's not like your time is inherently more valuable than hers, particularly if she has no earthly idea who you are or that you even exist.
Now, there are many open source projects who purport to be trying to scratch society's itches and who fail to do a reasonable job of making it easy for society: limited docs, no precompiled binaries for common platforms, no easy APIs or tutorials, etc. For those projects, your beef is understandable. But just because it's open source does not mean that there is a rule that it has to be documented well.
Posted by Mark Murphy at Sat Sep 13 12:12:25 2003
Mark,
I think it's a problem of motivation. If you really are writing software to only scratch your own itch, then why are you releasing it to the public? If I just wanted to record my ideas for myself or my family, I could keep a paper journal, or store a bunch of files on my computer.
Publishing your code, or just your ideas (like on a weblog) is a social act. You're trying to interact with the world. In doing so, you're establishing a sort of community of like-minded individuals, either by attracting people who already think that way, or by encouraging them to form an opinion similar to yours.
And as I said before, it's not the failure to document that I take issue with. Honestly, I'm as bad as the next person about documenting code. It's the refusal to acknowledge that this detracts from the code. It's the outright insistance that is myinadequacy, not theirs, that prevents me from using their code. This is what I take issue with.
Online communities of all sorts, including developer comminities, have this problem. People mistakenly believe that if they throw a party, everyone should show up and be happy there's a party, without demanding anything from the host at all. In the real world, if people show up to the party, and if the place is messy, and there aren't enough chairs or drinks, and the host tells everybody what to do, people get pissed off and leave.
Your parents might try to use the "while you're a guest in my house, you'll do as I say" emotional blackmail, but nobody tolerates it from their peers, except online! People, both the hosts and some of the guests, believe that it's perfectly alright for the host of an electronic community to be a complete jerk and everyone should still appreciate all they've done for them. Why do we put up with it?
Posted by Jason Marshall at Sat Sep 13 14:58:07 2003
I think it's a problem of motivation. If you really are writing software to only scratch your own itch, then why are you releasing it to the public? If I just wanted to record my ideas for myself or my family, I could keep a paper journal, or store a bunch of files on my computer.
Publishing your code, or just your ideas (like on a weblog) is a social act. You're trying to interact with the world. In doing so, you're establishing a sort of community of like-minded individuals, either by attracting people who already think that way, or by encouraging them to form an opinion similar to yours.
And as I said before, it's not the failure to document that I take issue with. Honestly, I'm as bad as the next person about documenting code. It's the refusal to acknowledge that this detracts from the code. It's the outright insistance that is myinadequacy, not theirs, that prevents me from using their code. This is what I take issue with.
Online communities of all sorts, including developer comminities, have this problem. People mistakenly believe that if they throw a party, everyone should show up and be happy there's a party, without demanding anything from the host at all. In the real world, if people show up to the party, and if the place is messy, and there aren't enough chairs or drinks, and the host tells everybody what to do, people get pissed off and leave.
Your parents might try to use the "while you're a guest in my house, you'll do as I say" emotional blackmail, but nobody tolerates it from their peers, except online! People, both the hosts and some of the guests, believe that it's perfectly alright for the host of an electronic community to be a complete jerk and everyone should still appreciate all they've done for them. Why do we put up with it?
Posted by Jason Marshall at Sat Sep 13 14:58:07 2003
Can't sat I agree Jason. I create some code to scratch an itch of my own. Rather than seeing this code vanish into my own CVS repositories, I easily push it out onto a site.
I've done this a fair few times and had people come across it 2 years later and be interested in what it was. Now, it didn't help them much as I'd stopped playing with it, but at least it was there for them to see.
I do agree however that there should be more architectual diagrams and more HowTo documents, but I very rarely see this in any kind of product. Open source is just the only one open enough to let you complain about it with the belief that things might change.
Posted by Henri Yandell at Sat Sep 13 23:20:10 2003
I've done this a fair few times and had people come across it 2 years later and be interested in what it was. Now, it didn't help them much as I'd stopped playing with it, but at least it was there for them to see.
I do agree however that there should be more architectual diagrams and more HowTo documents, but I very rarely see this in any kind of product. Open source is just the only one open enough to let you complain about it with the belief that things might change.
Posted by Henri Yandell at Sat Sep 13 23:20:10 2003
I'm interested in open source projects that involve a community. So while single person scratch your itch projects can be useful, those aren't really the projects I was thinking of.
The issue is a deep one, and it's not going to be solved by showing up and saying "why don't you lazy people write some decent docs". That's the reverse of being told "go read the source, you moron".
I've written before about a "rating" system or community that could be used as a way to help people steer clear of the JCP by recommending good open source projects as alternatives. One effect of having such a system or community could be to force people to deal with the doc issue (among others).
Posted by Ted Leung at Sun Sep 14 01:20:58 2003
The issue is a deep one, and it's not going to be solved by showing up and saying "why don't you lazy people write some decent docs". That's the reverse of being told "go read the source, you moron".
I've written before about a "rating" system or community that could be used as a way to help people steer clear of the JCP by recommending good open source projects as alternatives. One effect of having such a system or community could be to force people to deal with the doc issue (among others).
Posted by Ted Leung at Sun Sep 14 01:20:58 2003
Ted Leung on the air : computers/open_source/580 : I don't want to read your damned source code Various comments on this posting highlight some of my thoughts of late regarding open source software and developing it. It appears to me...
Posted by Trackback from soupblog at Sun Sep 21 13:35:42 2003
Posted by Trackback from soupblog at Sun Sep 21 13:35:42 2003
You can subscribe to an RSS feed of the comments for this blog:
Add a comment here:
You can use some HTML tags in the comment text:
To insert a URI, just type it -- no need to write an anchor tag.
Allowable html tags are:
You can also use some Wiki style:
URI => [uri title]
<em> => _emphasized text_
<b> => *bold text*
Ordered list => consecutive lines starting spaces and an asterisk
Add a comment here:
You can use some HTML tags in the comment text:To insert a URI, just type it -- no need to write an anchor tag.
Allowable html tags are:
<a href>, <em>, <i>, <b>, <blockquote>, <br/>, <p>, <code>, <pre>, <cite>, <sub> and <sup>.You can also use some Wiki style:
URI => [uri title]
<em> => _emphasized text_
<b> => *bold text*
Ordered list => consecutive lines starting spaces and an asterisk
![[Valid RSS]](http://www.sauria.com/blog/images/valid-rss.png "Validate my RSS feed"){kind=small}
