
Stop Writing Bullshit Documentation - blasdel
http://jfm3-repl.blogspot.com/2010/03/stop-writing-bullshit.html
======
jwhite
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
Java as well.

------
hubb
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

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

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

------
viraptor
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
Or examples that defy the description?

~~~
jbarciauskas
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.

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

