News for hackers. Stuff that matters.
Re:Why I still don’t contribute to open source by vacri on Tuesday May 03, 2011 @11:16PM (#2512648)
If you understand English, you can write documentation.

The bar is a lot higher than that. You have to understand English and understand the functions themselves. Sometimes even getting bullet-point list of functionality out of devs is like pulling teeth - leaving you with nothing to document in the first place. Similarly an understanding of why something was designed a certain way helps angle the documentation more accurately.

Clean documentation is hard, and doubly so if you're not the person who wrote X module for OpenFoo.

Re:Why I still don’t contribute to open source by briancurtin on Wednesday May 04, 2011 @09:28AM (#2513729)
> The bar is a lot higher than that. You have to understand English and understand the functions themselves.

In general, you're certainly correct. I was thinking too much about Python, where there's a strict but easy to follow guideline that all public APIs are documented, so the lowest level work has already been done. Because of that, there aren't a ton of places where you'd need a super deep understanding of the code in question to make a documentation impact. A lot of it is updating, removing, and reformatting. You'll see a lot more "reformat this paragraph as a table" issues than "write the whole doc for the wizbang module", the former being a fairly easy task.

Re:Why I still don’t contribute to open source by leon_ on Wednesday May 04, 2011 @02:41AM (#2512993)
Also if you understand the project well enough to write documentation you have to have the ability to put yourself into a new user's position. Many people lack this ability and create just unusable docs.
Re:Why I still don’t contribute to open source by jwhite on Wednesday May 04, 2011 @04:07AM (#2513125)
Agreed. It's a hard skill even when you're trying consciously. One way to improve the situation is to actually give your draft documentation to a trusted user for feedback. I've been lucky enough to have an enthusiastic user in-house who has road-tested some of my documentation, and it's much better for the exercise.