Live data from Hacker News

WTFM - Write The Freaking Manual

floopsy.com

31–40 of 82 posts

Re: WTFM - Write The Freaking Manual

#31

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…

Python docs may not be exactly beginner friendly, but it's certainly not terrible.

Re: WTFM - Write The Freaking Manual

#32
post #29

Reminds 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…

I think his point was more that clearly the developers want people to use what they built. So taking that extra step and writing good documentation would only help ensure that people used their software. Not doing so actually hurts their chances. Not doing so and expecting SOMEONE ELSE to do it is just dumb.

Re: WTFM - Write The Freaking Manual

#33

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…

Why is the Python documentation terrible in this respect? Python comes with a language reference[1], that has most of the components you ask for (one of the components is in a document that's called something other than the language reference, but that's because it's the stdlib, not the language itself... it's certainly the same style of document, not a tutorial!):

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.

[1] http://docs.python.org/reference/

Re: WTFM - Write The Freaking Manual

#34

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…

What do you reproach to python and coffeescript docs? I find them very good and very usable. I want to do something? I have the answer nearly immediately (well except for some shitty modules in python (I'm looking at you urllib(2)/popen)) and it's a real pleasure to use them while coding.

Re: WTFM - Write The Freaking Manual

#36

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…

I don't see why you say that Python docs are terrible while PHP docs are good. Can you provide details? Are you sure this isn't just a matter of liking certain conventions over others?

Re: WTFM - Write The Freaking Manual

#38
post #22
post #16

Earlier 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…

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.

Re: WTFM - Write The Freaking Manual

#39
post #16
post #2

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…

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…

This is an understatement. Even if Github is just a place to put your toy library/project and it's not being promoted, there should be an awesome README showing off what it is meant to do (even if it doesn't do that yet, just point out that those features aren't yet available). When I find engineers on Github who've contributed to projects I enjoy using and I look through their repositories to find projects with interesting names but NO README, I get annoyed. I don't mind reading code, but sometimes I just want to see what this thing does before I go about reading 2 thousand lines of code.

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

#40
post #16
post #2

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…

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…

Good for you. Don't use my open source stuff. Turns out I wrote it for me, whether you get anything out of it or not doesn't actually affect me. If you do get something out of it, great. If you contribute great. But unless you are paying me, don't tell me what I should be doing with my hobby time. Period, end of story, full stop. Take your demands to someone else.

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.

Post reply on HN