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

11–20 of 82 posts

Re: WTFM - Write The Freaking Manual

#11

Post by threedaymonk »

orangethirty wrote: post #5
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…

You can run the source through one of those automated documentation tools like doxygen. That does make a big difference.

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 complicated case than it is to go from nothing to even a simple case.

To pick on a specific project, Treetop http://treetop.rubyforge.org/ has a pretty detailed set of documentation (human-generated, not automated), but I found it quite hard to go from the abstract enumeration of its features to actual working code. So hard, in fact, that I wrote up an introduction to help others, and it's been a very popular page: http://po-ru.com/diary/getting-started-with-treetop/

Re: WTFM - Write The Freaking Manual

#12

Post by qznc »

fellars wrote: post #6

Any pointers on how to make it easier to wtfm? If anyone out there actually enjoys writing documentation I'd be willing to pay for some help and guidance on a rather large commercial open source project that is in need of some tlc regarding documentation

Sphinx is pretty nice, even if it is not a python project.

http://sphinx.pocoo.org/

Re: WTFM - Write The Freaking Manual

#13

Post by takluyver »

fellars wrote: post #6

Any pointers on how to make it easier to wtfm? If anyone out there actually enjoys writing documentation I'd be willing to pay for some help and guidance on a rather large commercial open source project that is in need of some tlc regarding documentation

In the Python world, readthedocs.org has made writing docs easier - it takes care of rebuilding documentation each time you commit. It's implemented in Python, and most popular with the Python community, but it can be used for other languages as well.

Re: WTFM - Write The Freaking Manual

#14

Post by FiddlerClamp »

fellars wrote: post #6

Any pointers on how to make it easier to wtfm? If anyone out there actually enjoys writing documentation I'd be willing to pay for some help and guidance on a rather large commercial open source project that is in need of some tlc regarding documentation

I'm a marketing and technical writer - take a look at the URL in my profile and get in touch if you are interested.

Re: WTFM - Write The Freaking Manual

#15

Post by jackalope »

And please, WTFV isn't enough. I don't have time to watch or search through a 40 minute video to find out how to set a few configuration options. Text is king when it comes to documentation. Videos are fine for tutorial purposes, but I need a solid reference that's well indexed and searchable.

Re: WTFM - Write The Freaking Manual

#16

Post by Swizec »

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…

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

Re: WTFM - Write The Freaking Manual

#17

Post by nathan_long »

jackalope wrote: post #15

And please, WTFV isn't enough. I don't have time to watch or search through a 40 minute video to find out how to set a few configuration options. Text is king when it comes to documentation. Videos are fine for tutorial purposes, but I need a solid reference that's well indexed and searchable.

Video is also a poor replacement for text because it is MUCH more laborious to create and update, so it probably won't be updated.

If someone were willing to make a video, writing text should be a given.

Re: WTFM - Write The Freaking Manual

#18

Post by jobu »

Good documentation is really hard to do, but it's also one of the most important things for any product or project. If no one uses what you make then it truly is useless, and you will never get people to use something unless they can figure out how.

Re: WTFM - Write The Freaking Manual

#19

Post by nathan_long »

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 documentation is clear, thorough, and gives examples of usage, I'm likely to trust your project and dig deeper.

It's even been argued that writing the docs first helps you develop better: http://tom.preston-werner.com/2010/08/23/readme-driven-devel...

Re: WTFM - Write The Freaking Manual

#20

Post by nathan_long »

threedaymonk wrote: post #11
orangethirty wrote: post #5

Earlier quoted context omitted.

You can run the source through one of those automated documentation tools like doxygen. That does make a big difference.

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

Post reply on HN