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

51–60 of 82 posts

Re: WTFM - Write The Freaking Manual

#51

Post by dredmorbius »

aidenn0 wrote: post #37

I think after you write a manual for your first few projects and clearly less than 1% of your users read it, it gets hard to motivate yourself to write another manual.

The advantage of documentation isn't that users read it before asking questions.

It's that you answer questions by pointing at the relevant section of the docs.

If that section doesn't exist, it's a good practice to see that it does (either write it yourself, have another contributor write it, or encourage the person asking the question to submit a doc).

Re: WTFM - Write The Freaking Manual

#52

Post by brudgers »

The root of this issue is that writing documentation is not something that really good hackers like to do...these days [1].

And it's damn sure not something that good writers are interested in...unless they are paid. Paying good writers to write documentation is not a core competency of the FOSS community, nor part of its ethos.[2]

[1] These days being the age of the internet and languages implementing brogrammar. People like McCarthy and Knuth wrote their own documentation to a dead tree publication standard, not a rough draft of a Wiki standard.

[2] Erlang and Go aren't going to give the world another RPG or PG writing passionately about their wonders.

Re: WTFM - Write The Freaking Manual

#53

Post by pnathan »

brudgers wrote: post #52

The root of this issue is that writing documentation is not something that really good hackers like to do...these days [1]. And it's damn sure not something that good writers are interested in...unless they are paid. Paying good writers to write documentation is not a core competency of the FOSS community, nor part of its ethos.[2] [1] These days being the age of the internet and languages implementing brogrammar. Pe…

One thing I've done a few times is to help out just by writing docs for open source projects.

I know it's a drag. I know it's not that much fun. But it massively - MASSIVELY - improves the project's value, especially if it's low on the totem pole.

Re: WTFM - Write The Freaking Manual

#54

Post by brudgers »

pnathan wrote: post #53
brudgers wrote: post #52

The root of this issue is that writing documentation is not something that really good hackers like to do...these days [1]. And it's damn sure not something that good writers are interested in...unless they are paid. Paying good writers to write documentation is not a core competency of the FOSS community, nor part of its ethos.[2] [1] These days being the age of the internet and languages implementing brogrammar. Pe…

One thing I've done a few times is to help out just by writing docs for open source projects. I know it's a drag. I know it's not that much fun. But it massively - MASSIVELY - improves the project's value, especially if it's low on the totem pole.

But of course, your profile lists lisp.

Re: WTFM - Write The Freaking Manual

#55

Post by eblume »

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…

Package installation is a known pain point in python. The problem is one of a plethora of half-baked solutions.

For now, you can get most of the way by trying 'pip install X' or 'easy_install X', but there are important edge cases.

It's being worked on for Python 3's next big release, last I heard.

Re: WTFM - Write The Freaking Manual

#56

Post by reinhardt »

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'm still unclear what the standard method for managing these is.

If only this was just a documentation issue. Alas, the reason is that there is no standard method. Here's a short practical article on how to install Python packages and get on with your life: http://dubroy.com/blog/so-you-want-to-install-a-python-packa.... For a longer historical perspective of this whole clusterfuck check out http://lucumr.pocoo.org/2012/6/22/hate-hate-hate-everywhere/

Re: WTFM - Write The Freaking Manual

#57

Post by reinhardt »

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 techniques is way out of touch with how most people actually learn.

Re: WTFM - Write The Freaking Manual

#60

Post by demewmew »

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 learn in a variety of different ways, and I'm also a developer who always prefers a reference manual over learn-by-example techniques. You may not be one of those developers, but that doesn't mean we don't exist. I imagine there are plenty of people who don't learn by the reference manual but would prefer to have it available - if it was available - as well.
Post reply on HN