I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it se…
WTFM - Write The Freaking Manual
31–40 of 82 posts
Re: WTFM - Write The Freaking Manual
#32Reminds me of the old expression: "fast, cheap, good. pick two." When we were largely buying shrink wrapped software they almost all came with decent sized manuals (quality varied, of course). He tagged the post with a bunch of open source projects, which has almost never been an area of good manuals. It's very uncommon for "scratching your own itch" to lead to comprehensive documentation for obvious reasons. Develop…
Re: WTFM - Write The Freaking Manual
#33I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it se…
1. Syntax (sections 5, 6, 7 and I guess also 9 if you want the full grammar)
2. Whitespace (section 2.1)
3. Operation priority (section 5.15 has it explicitly, the rest of the sections also clarify)
4. All functions, types, classes... both globals and stdlib modules are documented in http://docs.python.org/library/index.html#library-index
5. All parameters? Documentation should already have these.
6. Callback parameters: I can't think of any callbacks in the stdlib offhand, but the ones that do exist are methods you implement, and all the ones I can think of are documented
7. Default values and their meanings are pretty much always documented
8. I don't know what flag values are, but if they're just parameters they fall under (5)
9. Return values and exceptions should always be documented
10. There are plenty of cases where some input parameters causing undefined behavior is documented; some maybe not (for example I don't think urlparse.urlsplit documents what happens when you give it a scheme it doesn't know about), but MOSTLY it's documented.
Re: WTFM - Write The Freaking Manual
#34I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it se…
Re: WTFM - Write The Freaking Manual
#35Re: WTFM - Write The Freaking Manual
#36I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it se…
Re: WTFM - Write The Freaking Manual
#37Re: WTFM - Write The Freaking Manual
#38Earlier quoted context omitted.
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 solutio…
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…
Re: WTFM - Write The Freaking Manual
#39When 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…
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 solutio…
The worst thing that could happen is that someone would want to start using your library while it's in an alpha state, and then complain that it's not perfect. But in the end, if people would really find something you're working on useful, you might get a lot of community support and motivation to finish it, so why not?
And as you state, when features are completed, there should be pages with ample examples on how to use them. Programmers can usually read a code example ten to a hundred times faster than they can read over the documentation for everything used in that example, and in well written code, the expected functionality (that is: documented behavior) is clear from an example alone. Programmers can also write a quick code example with a few inline comments faster and better than they can write good documentation.
Re: WTFM - Write The Freaking Manual
#40When 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…
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 solutio…
Further, demands for great documentation are unreasonable. I can point to hundreds of examples of 'well documented' projects where I still dig into the source code and do simple experiments to learn what the heck it does. This is a combination of how I learn and how I use software. Your docs (for all values of you) are crappy and don't tell me how the software works - the code does that tho, so I actually can trust it. If you want to do truely great documentation, put some comments of expected use at the top of the function/class/whatever definition, some comments on tricky sections of code (not "this does the file read" i get that from the call to read(), but "this also triggers an event from the OS handled in foohandler()), and good clean loosely coupled components.