3 ms·

Stop Writing Bullshit Documentation

42 points by blasdel 17y ago

viraptor 17y ago
Instantly thought of http://www.the-asterisk-book.com/ 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 17y ago
  Or examples that defy the description?
  - jbarciauskas 17y 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 17y 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 17y 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 17y 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 17y 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 http://fedoraproject.org/wiki/Joining_the_Docs_Project
hubb 17y 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 17y ago
only a chosen few OS projects have good documentation so I would say that this is nothing new.
jff 17y 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 17y 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 17y ago
  Java as well.

42 points by blasdel 17y ago

Instantly thought of http://www.the-asterisk-book.com/ 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 17y ago
Or examples that defy the description?
- jbarciauskas 17y 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 17y 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 17y 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 17y 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 17y 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 http://fedoraproject.org/wiki/Joining_the_Docs_Project

hubb 17y 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 17y ago

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

jff 17y 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 17y 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 17y ago
Java as well.