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

61–70 of 82 posts

Re: WTFM - Write The Freaking Manual

#61

Post by [deleted] »

nathan_long wrote: post #20
threedaymonk wrote: post #11

Earlier quoted context omitted.

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

+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

[deleted]

Re: WTFM - Write The Freaking Manual

#62

Post by incision »

This is one of the reasons I consider my Safari subscription indispensable.

It provides immediate access to generally well-written and structured documentation and instruction covering a wide range of topics. The one downside would be the obvious lack of bleeding edge topics as those books have yet to be written.

Re: WTFM - Write The Freaking Manual

#63

Post by incision »

dredmorbius wrote: post #49

I fully endorse this. Coming from a sysadmins / devopps perspective, documentation is key to providing a reliable, dependable, available, scalable service. And dramatically improving the quality of my life. How that documentation is written also matters. A lot . Much proprietary documentation is also crap, for numerous reasons. Marketing having too much say is key (every reference to a Trademarked(r) Name(tm) Phrase(…

Coming from the same perspective, I agree completely.

Software pushers all seem to give the same puzzled look when I ask to see their full docs before evaluating their product.

It's exactly as you describe, if the documentation isn't sufficient for me to learn everything I could possibly need and likely want to know about how things work - I can't confidently design, build, scale or support it.

Documentation in the "Enterprise" world seems almost intentionally bad, as if to force customers into professional services and support contracts for products which lack the proper design to be sold as full on SaaS.

Re: WTFM - Write The Freaking Manual

#64

Post by xtracto »

nathan_long wrote: post #19
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 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.

Re: WTFM - Write The Freaking Manual

#65

Post by irreverentbits »

sophacles wrote: post #40
Swizec wrote: 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…

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 software is that it enables individuals to program against a documented interface without spending (although in many cases I'd say wasting) time to understand the intricacies of implementation. You lose that benefit if you're forced to dip into code to understand how to use that code.

You do have a point, though - as an open source dev, it's your time to spend as you see fit. But a quality open-source project is more than the sum of its code.

Re: WTFM - Write The Freaking Manual

#66

Post by blahedo »

Relevant, I think:

http://www.ginandtacos.com/2012/09/24/tab-a-slot-b

In it, the author speculates that one of the reasons that kids have such a hard time following directions is that they never learn to read them, because nothing comes with directions anymore (you just "figure it out"). It's sort of the dark side of ubiquitous discoverable UI.

Re: WTFM - Write The Freaking Manual

#67

Post by dreamdu5t »

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…

"It's 2012, nobody reads dry reference manuals cover to cover" speak for yourself and stop making sweeping assumptions when you actually have no clue.

Re: WTFM - Write The Freaking Manual

#68

Post by trhtrsh »

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…

http://golang.org/doc/

http://research.swtch.com/

Re: WTFM - Write The Freaking Manual

#69

Post by pnathan »

brudgers wrote: post #54
pnathan wrote: post #53

Earlier quoted context omitted.

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.

I beg pardon, what do you mean by that?

Re: WTFM - Write The Freaking Manual

#70

Post by dredmorbius »

protomyth wrote: post #28
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…

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).

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.

Post reply on HN