Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

WTFM - Write The Freaking Manual

floopsy.com

Post reply on HN
Print view View original

71–80 of 82 posts

Re: WTFM - Write The Freaking Manual

#71

Post by samspot »

reinhardt wrote: post #57
crazygringo wrote: post #27

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…

You're in a small minority, what you want and don't want is irrelevant. It's 2012, nobody reads dry reference manuals cover to cover, nevermind doing so before firing up a shell window and an editor. Reference manuals are still nice to have of course for clarifying edge cases and solving language lawyer disputes. However claiming that they are a superior learning and time-saving tool than the learn-by-example techniq…

I don't read them cover to cover, but I need info on specific subjects quite often, and some tools just don't have it.

Re: WTFM - Write The Freaking Manual

#72

Post by ZoFreX »

irreverentbits wrote: post #65
sophacles wrote: post #40

Earlier quoted context omitted.

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

Yeah, see, here's the thing: for many projects of noteworthy complexity, it'll be easier to gain an understanding of how to make use of it through a clear set of docs than it will be by slogging through source code. Good documentation provides context and use cases. Good comments in source code provide clarity as to what the code is doing. They are in no way equivalent. One of the benefits of encapsulation in softwar…

> You do have a point, though - as an open source dev, it's your time to spend as you see fit

I agree with both of you - I don't see software as "complete" unless it has documentation, it's part of the package to me. I happen to like writing it, but I hate some other aspects of programming - doesn't mean I skip those sections.

However, I have put things online without documentation before, because the software wasn't complete but maybe someone else would complete it, or find it useful, or learn something from it. Maybe they won't - but I lose nothing by putting it online, and the world stands to gain.

Re: WTFM - Write The Freaking Manual

#73

Post by burntsushi »

exDM69 wrote: 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…

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.

Re: WTFM - Write The Freaking Manual

#74

Post by adhipg »

Zelphyr wrote: post #30
crazygringo wrote: post #27

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…

You mention CoffeeScript being one of the worst, and I don't necessarily disagree, but how has it become so popular despite its poor documentation? Is it because CS is just /that/ good? Or is it that it has developed a great community early on that compensates for the lack of documentation? Either way, writing good documentation seems like an either path than doing those two things.

There's also a third reason: it's very easy to see what CoffeeScript compiles to - the JavaScript source is easy enough to read and comprehend - and that behaviour is well documented.

Most of the times I'm looking at CoffeeScript to just figure out what it compiles to!

Re: WTFM - Write The Freaking Manual

#75

Post by brudgers »

pnathan wrote: post #69
brudgers wrote: post #54

Earlier quoted context omitted.

But of course, your profile lists lisp.

I beg pardon, what do you mean by that?

Lisp has a literary tradition stronger than other languages. See Richard P. Gabriel, or Paul Graham for that matter. Python and Cpp may have polemics, but none as useful as Let Over Lambda.

Re: WTFM - Write The Freaking Manual

#76

Post by orangethirty »

There is a big need here waiting to be satisfied. Documentation is very important and a lot of projects are losing traction due not having the basics or it being done poorly. I'm actually working with a new platform by writing their documentation for them. Why would I do that? I have a talent for it, and it allows me to offer a service other full-stack engineers won't even think about doing. Writing documentation as a job is a great way to improve my engineering skills. If I can explain it to people, then I definitely know how something works.

Re: WTFM - Write The Freaking Manual

#77

Post by mememememememe »

reinhardt wrote: post #57
crazygringo wrote: post #27

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…

You're in a small minority, what you want and don't want is irrelevant. It's 2012, nobody reads dry reference manuals cover to cover, nevermind doing so before firing up a shell window and an editor. Reference manuals are still nice to have of course for clarifying edge cases and solving language lawyer disputes. However claiming that they are a superior learning and time-saving tool than the learn-by-example techniq…

People in the hardware or embedded system industry have to read it page by page, word by word because they do. People who actually design compilers have that too. People who actually work with specs like Mozilla have a big manual too. People who actually use a 3rd-party product and integrate them into their product have to read those manuals a hundred times including meeting with the vendor.

If you are only doing your own product using Python libraries, then certainly you don't.

Re: WTFM - Write The Freaking Manual

#78

Post by klodolph »

slurgfest wrote: post #36
crazygringo wrote: post #27

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?

It's a recurring argument on HN whether Python docs are good. Someone claims they're terrible, and someone always asks, "Why? I think the docs are good!"

There's a critical gap between the expectations of Ruby/Java programmers of how to write Python and the way Python programmers behave. I think it really is cultural, to an extent. The Java programmers look for Java-style documentation, with classes and methods and lists of exceptional conditions. The Ruby programmers look for Ruby-style documentation, with lots of diversions into the "why" of things and the context, possibly with pictures of foxes.

A Python programmer would consider the Java docs needlessly detailed and the Ruby docs a bit fluffy and not to the point, but after all, it is just a matter of viewpoint, community goals, and culture. There's also the issue of installing packages in Python, which can be a bit of a bummer, but I've never had a problem downloading a Python package from some site and following the directions.

Re: WTFM - Write The Freaking Manual

#79

Post by radiac »

xtracto wrote: post #64
nathan_long wrote: post #19

Earlier quoted context omitted.

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

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.

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.

Re: WTFM - Write The Freaking Manual

#80

Post by lvh »

tibbon wrote: post #42
lvh wrote: post #33

Earlier quoted context omitted.

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

I program in Ruby most days. A while back I was trying to figure out something in Python. Python isn't hard, and I can read it (since its practically like reading Ruby) and get by writing it here and there when needed. So... I'm trying to use some Python library (whatever your equivalent of a Gem is). I spent a few hours ripping out my hair trying to find good documentation for how to install and manage Python librar…

I think this might be an issue with what you're used to. We have things like rvm, gems and bundler: look at virtualenv, distutils/setuptools... The equivalent of a Gemfile is a requirements file, pip knows how to install these (pip install -r FILE).

If you ask me to do the same in Ruby, I'd probably be lost too.

Post reply on HN