Stop Writing Bullshit Documentation

http://jfm3-repl.blogspot.com/2010/03/stop-writing-bullshit.html

by blasdel • 16 years ago

42 12 16 years ago

jfm3-repl.blogspot.com

viraptor• 16 years ago

Instantly thought of http://www.the-asterisk-book.com/

I wonder if that was the reason for the post... Does anyone else know examples matching the description?

wmat• 16 years ago

Or examples that defy the description?

jbarciauskas• 16 years ago

Somewhere between step 3 and 5 it goes down a rathole that just does not apply to most projects I've used (Spring, commons-*, iBatis, Wicket...) Of course, configure and install don't really apply to Java, doubly so now with Maven repositories...

The Maven archetype concept might be one of the greatest tools invented so far in combating the type of "intro tutorial" BS writing described here.

blantonl• 16 years ago

one might argue that the process of participating in open source projects shouldn't be limited to ./configure; make, make install; complain in blog post.

Furthermore, one might argue that actively participating in open source projects doesn't mean that "svn commit" is the only action you make towards the project.

Folks, consider starting a documentation project for an open source project that doesn't have one, and one for which you are interested in. you might learn more about the project by going through that process.

ambiate• 16 years ago

I would absolutely love to do this! I'm just not sure where to start(browse github?) or how to approach a team (re: introvert). I hate to look like the sad-eyed puppy waiting for a bone...

jackowayed• 16 years ago

GitHub would be a good place to start, but really it should be a project you've used a fair amount and that you really like.

No need to approach them. If you want to fill in the gaps in the docs they have, then fork the project, improve the documentation, and send them a pull request. If you want to start a separate project documenting the project, whip something up that's decent but doesn't take you too long and send them a GitHub message.

Don't be shy. The sense I get is that people that want to do documentation are extremely hard to come by, so most OSS project leaders would jump for joy if they got a message about someone improving documentation for their project.

mapleoin• 16 years ago

If you're just starting out, it might be easier for you to join an existing team and learn from the more experienced members. The Fedora Project is geared toward contributors and is very friendly towards new ones especially. You usually just have to send an email to the list of the team you want to participate in or drop by the IRC channel. Someone will then start you working on whatever you want to do.

http://fedoraproject.org/wiki/Joining_the_Docs_Project

hubb• 16 years ago

having recently read the documentation for the linux kernel, open embedded, and bitbake, i'm pretty tired of bullshit -- but even more tired of 'TODO' and 'THIS ARTICLE IS A STUB' appearing in web pages that aren't wikis

jister• 16 years ago

only a chosen few OS projects have good documentation so I would say that this is nothing new.

jff• 16 years ago

See: any documentation on GStreamer, as I rapidly discovered last fall when I attempted to use it for a project. Many of the components are pretty much undocumented; I was reduced to finding blog posts where some guy says "Hey, I streamed a video to a different computer with this command line", then figuring out how exactly you're supposed to instantiate these things in C, string them all together, use the disgusting object system, etc.

jwhite• 16 years ago

Also, stop thinking that doxygen output from your source code qualifies as adequate documentation. (Insert whatever comment-embedded-docstring-auto-extraction tool your language supports, if not doxygen.)

It's great as a reference, but woeful to learn from.

Ruby libraries, I'm looking at you.

ytinas• 16 years ago

Java as well.

Stop Writing Bullshit Documentation

Related Stories