5 ms·

When it comes to open source work, which I mostly do on my own, limited time and don't get paid for, I have a choice. I can spend time writing code or writing d

by exDM69 14y ago

When it comes to open source work, which I mostly do on my own, limited time and don't get paid for, I have a choice. I can spend time writing code or writing documentation. The former I enjoy very much, the latter I don't like at all. Guess which I am going to pick. The times when I've actually ended up writing some docs, I don't think anyone has ever read them. And writing the docs is just the beginning, they have to be maintained too. Out of date docs are perhaps worse than no docs at all. I don't read docs either, because they tend to be out of date. Formal specifications are an exception. But when it comes to open source, I just tend to read the source because it's never out of date and tells the whole story. What was obvious to writer of the doc isn't obvious to me and vice versa. The first person who comes to me asking for documentation to my projects volunteers to write them, like it or not.

orangethirty 14y ago
You can run the source through one of those automated documentation tools like doxygen. That does make a big difference.
- threedaymonk 14y ago
  Honestly, I'm not sure it does. I've seen plenty of software projects whose documentation consists of an automated compendium of every method in every class, none of which tells me how to actually use it. I'd prioritise a simple getting started guide. It only has to be a page or so, but something that explains how to run the program, and achieve a few simple tasks. It's far easier to go from a simple case to a more complicated case than it is to go from nothing to even a simple case. To pick on a specific project, Treetop http://treetop.rubyforge.org/ http://treetop.rubyforge.org/ has a pretty detailed set of documentation (human-generated, not automated), but I found it quite hard to go from the abstract enumeration of its features to actual working code. So hard, in fact, that I wrote up an introduction to help others, and it's been a very popular page: http://po-ru.com/diary/getting-started-with-treetop/ http://po-ru.com/diary/getting-started-with-treetop/
  - nathan_long 14y ago
    +1. If I wanted to rummage through a pile of classes and methods to figure out where to start, I'd just read the code. I want a conceptual overview, usage examples, and some discussion of edge cases. I've rabidly documented my Rails authorization library, and I'd attribute most of the attention it's gotten to the documentation. https://github.com/nathanl/authority https://github.com/nathanl/authority
    - deleted 14y ago
      [deleted]
xradionut 14y ago
I've wasted hundreds of hours dealing with piss-poor or no documentation, reading/debugging code, searching sites and forums just to find the magical combo of steps that get a application to build correctly or an LED to blink. I don't have unlimited time to figure out your code, API and lack of documents. I would rather deal with OSS or commercial software that respects me.
Swizec 14y ago
Conversely, I don't even use open source software that doesn't have a simple README on Github showing me plentiful examples on how to use the damn library. Sorry, if you don't have documentation, even a little bit, you're just not worth my time. There are at least two other libraries out there with better documentation. The fact they might be worse software doesn't even matter because all I'm looking for is a solution.
- exDM69 14y ago
  GitHub READMEs are an excellent compromise. Doing more detailed docs are quite a lot of effort (that is better spent coding), especially to projects that are at an early stage. Projects which are an early stage (like most of my projects) should mostly try to attract potential contributors, not just consumers/end-users so it's not unreasonable to require would-be users/contributors to walk the extra mile and actually read (at least parts of) the source. I do that even for projects that are well established with docs if I intend to depend on them. If there actually were libs that are well documented and do the same thing, I wouldn't have started the projects I did but contribute to the existing projects instead. This may not be true for all kinds of projects.
  - rgbrgb 14y ago
    There's a double standard here. You want developers to contribute to your project despite the lack of documentation but you require that libraries you contribute to are well documented.
    - exDM69 14y ago
      > ...but you require that libraries you contribute to are well documented. You misread me. I almost never read the docs because they suck more often than not. I start from example and test source code and almost always end up reading parts or most of the source code.
      - rgbrgb 14y ago
        > If there actually were libs that are well documented and do the same thing... I thought you were implying that you required libs you contribute to to be well documented.
nathan_long 14y ago
> I can spend time writing code or writing documentation. You are selling yourself short. Your documentation the first thing people see. If it says "incomplete, confusing, and half-hearted", I'm going to hit the back button in about 15 seconds. I'm not going to spend 15 minutes reading your code to see if the first impression is wrong unless I think there's no viable alternative project. Conversely, if your documentation is clear, thorough, and gives examples of usage, I'm likely to trust your project and dig deeper. It's even been argued that writing the docs first helps you develop better: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html http://tom.preston-werner.com/2010/08/23/readme-driven-devel...
- protomyth 14y ago
  I remember reading a story about Pages for Pages on NeXTSTEP. The manual was done before the software, so if there was any design question about how the program should work, they turned to the manual. I think it was an article by Bruce Webster (he is an awesome writer).
  - dredmorbius 14y ago
    That's a code authoring technique I picked up from Code Complete. It's useful for keeping your code in conformance with documentation. The problem is when the original spec turns out to be impossible (or difficult/expensive) to implement, and needs to be changed. However if you doc then build, you've got a change control process that should accommodate this.
- xtracto 14y ago
  But the thing is that he is not selling himself at all. He writes some code for him and then maybe decides to release it as open source in case someone else finds it useful.
  - radiac 14y ago
    People who release undocumented code have no sense of social responsibility, and they are wasting everyone else's time. The only way you can figure out if these releases do what you want is to spend half an hour trawling through the source code. Over the years I must have wasted weeks of productive time doing just that, and I can't believe I'm the only person who has. I don't expect full API documentation and set of unit tests for every open source project - I'd be happy if most projects came with a short overview of how the code works, how it is implemented, maybe a couple of examples, and a list of its limitations. I do that for most projects I write for myself, to make it easier to come back to in a year or two when I next need to work on it. If your project isn't worth spending an hour writing some basic documentation, then it isn't worth releasing.
nollidge 14y ago
The sweet spot, I think, is a nice "getting started" guide along with an discoverable API design. The guide gives prospective users an idea what it's like to use the library, and the discoverableness means they'll be able to figure out the more complex stuff without precarious trial-and-error or obscure doc spelunking.
dredmorbius 14y ago
1. Figure out a way to get paid for it. 2. If you're designing tools for other people to use, documentation really, really, really matters. Even if it's just a mailing list and wiki initially. When I'm evaluating tools, I look to the docs, and if I find them lacking, my interest dims very, very rapidly. I'm a systems admin, and don't do much coding (though programmers have a need for docs as well). My main concerns are uptime, reliability, predictability, and well-understood behavior. If a tool shows a wild cowboy shoot-from-the-hip, damn the torpedoes mentality, it's going to make my life (and my sleep quantity and quality) hell. Life's too short for that shit.
burntsushi 14y ago
I think this is all well and good, so long as you're not looking to get people to use your code. If you want people to use your code, you need some kind of documentation. Otherwise, a lot of people (including myself) aren't even going to give you more than 30 seconds worth of time.

by exDM69 14y ago

orangethirty 14y ago

You can run the source through one of those automated documentation tools like doxygen. That does make a big difference.

threedaymonk 14y ago
Honestly, I'm not sure it does. I've seen plenty of software projects whose documentation consists of an automated compendium of every method in every class, none of which tells me how to actually use it. I'd prioritise a simple getting started guide. It only has to be a page or so, but something that explains how to run the program, and achieve a few simple tasks. It's far easier to go from a simple case to a more complicated case than it is to go from nothing to even a simple case. To pick on a specific project, Treetop http://treetop.rubyforge.org/ http://treetop.rubyforge.org/ has a pretty detailed set of documentation (human-generated, not automated), but I found it quite hard to go from the abstract enumeration of its features to actual working code. So hard, in fact, that I wrote up an introduction to help others, and it's been a very popular page: http://po-ru.com/diary/getting-started-with-treetop/ http://po-ru.com/diary/getting-started-with-treetop/
- nathan_long 14y ago
  +1. If I wanted to rummage through a pile of classes and methods to figure out where to start, I'd just read the code. I want a conceptual overview, usage examples, and some discussion of edge cases. I've rabidly documented my Rails authorization library, and I'd attribute most of the attention it's gotten to the documentation. https://github.com/nathanl/authority https://github.com/nathanl/authority
  - deleted 14y ago
    [deleted]

xradionut 14y ago

I've wasted hundreds of hours dealing with piss-poor or no documentation, reading/debugging code, searching sites and forums just to find the magical combo of steps that get a application to build correctly or an LED to blink. I don't have unlimited time to figure out your code, API and lack of documents. I would rather deal with OSS or commercial software that respects me.

Swizec 14y ago

Conversely, I don't even use open source software that doesn't have a simple README on Github showing me plentiful examples on how to use the damn library. Sorry, if you don't have documentation, even a little bit, you're just not worth my time. There are at least two other libraries out there with better documentation. The fact they might be worse software doesn't even matter because all I'm looking for is a solution.

exDM69 14y ago
GitHub READMEs are an excellent compromise. Doing more detailed docs are quite a lot of effort (that is better spent coding), especially to projects that are at an early stage. Projects which are an early stage (like most of my projects) should mostly try to attract potential contributors, not just consumers/end-users so it's not unreasonable to require would-be users/contributors to walk the extra mile and actually read (at least parts of) the source. I do that even for projects that are well established with docs if I intend to depend on them. If there actually were libs that are well documented and do the same thing, I wouldn't have started the projects I did but contribute to the existing projects instead. This may not be true for all kinds of projects.
- rgbrgb 14y ago
  There's a double standard here. You want developers to contribute to your project despite the lack of documentation but you require that libraries you contribute to are well documented.
  - exDM69 14y ago
    > ...but you require that libraries you contribute to are well documented. You misread me. I almost never read the docs because they suck more often than not. I start from example and test source code and almost always end up reading parts or most of the source code.
    - rgbrgb 14y ago
      > If there actually were libs that are well documented and do the same thing... I thought you were implying that you required libs you contribute to to be well documented.

nathan_long 14y ago

> I can spend time writing code or writing documentation. You are selling yourself short. Your documentation the first thing people see. If it says "incomplete, confusing, and half-hearted", I'm going to hit the back button in about 15 seconds. I'm not going to spend 15 minutes reading your code to see if the first impression is wrong unless I think there's no viable alternative project. Conversely, if your documentation is clear, thorough, and gives examples of usage, I'm likely to trust your project and dig deeper. It's even been argued that writing the docs first helps you develop better: http://tom.preston-werner.com/2010/08/23/readme-driven-development.html http://tom.preston-werner.com/2010/08/23/readme-driven-devel...

protomyth 14y ago
I remember reading a story about Pages for Pages on NeXTSTEP. The manual was done before the software, so if there was any design question about how the program should work, they turned to the manual. I think it was an article by Bruce Webster (he is an awesome writer).
- dredmorbius 14y ago
  That's a code authoring technique I picked up from Code Complete. It's useful for keeping your code in conformance with documentation. The problem is when the original spec turns out to be impossible (or difficult/expensive) to implement, and needs to be changed. However if you doc then build, you've got a change control process that should accommodate this.
xtracto 14y ago
But the thing is that he is not selling himself at all. He writes some code for him and then maybe decides to release it as open source in case someone else finds it useful.
- radiac 14y ago
  People who release undocumented code have no sense of social responsibility, and they are wasting everyone else's time. The only way you can figure out if these releases do what you want is to spend half an hour trawling through the source code. Over the years I must have wasted weeks of productive time doing just that, and I can't believe I'm the only person who has. I don't expect full API documentation and set of unit tests for every open source project - I'd be happy if most projects came with a short overview of how the code works, how it is implemented, maybe a couple of examples, and a list of its limitations. I do that for most projects I write for myself, to make it easier to come back to in a year or two when I next need to work on it. If your project isn't worth spending an hour writing some basic documentation, then it isn't worth releasing.

nollidge 14y ago

The sweet spot, I think, is a nice "getting started" guide along with an discoverable API design. The guide gives prospective users an idea what it's like to use the library, and the discoverableness means they'll be able to figure out the more complex stuff without precarious trial-and-error or obscure doc spelunking.

dredmorbius 14y ago

1. Figure out a way to get paid for it. 2. If you're designing tools for other people to use, documentation really, really, really matters. Even if it's just a mailing list and wiki initially. When I'm evaluating tools, I look to the docs, and if I find them lacking, my interest dims very, very rapidly. I'm a systems admin, and don't do much coding (though programmers have a need for docs as well). My main concerns are uptime, reliability, predictability, and well-understood behavior. If a tool shows a wild cowboy shoot-from-the-hip, damn the torpedoes mentality, it's going to make my life (and my sleep quantity and quality) hell. Life's too short for that shit.

burntsushi 14y ago

I think this is all well and good, so long as you're not looking to get people to use your code. If you want people to use your code, you need some kind of documentation. Otherwise, a lot of people (including myself) aren't even going to give you more than 30 seconds worth of time.