Slashdot Mirror

← Back to Stories (view on slashdot.org)

It's the Documentation, Stupid!

Posted by CmdrTaco on from the i-prefer-well-commented-source-code dept.

Roblimo writes "Brian Jones, a sysadmin for Princeton University, has written a Linux.com column that says open source developers need to provide better documentation if they expect support from sysadmins like him: 'With documentation, I can get to know the software,' he writes. 'Then I'll install it on a test box. If it works, great, I'm tickled pink. If it doesn't quite work, then I'm interested in giving feedback, because here's someone who will roll it back into the product or the documentation. This is a useful cycle that benefits millions, not the least of which is the coder! Documentation ends up resulting in a more mature product! Wake up!'"

4 of 105 comments (clear)

  1. Re:In other news... by Bob_Robertson · · Score: 2, Funny

    Pebs,

    I wish there were some way to lock this article so yours would be the only comment.

    Bob-

    --
    The Ludwig von Mises Institute. The reasoning individuals economics
  2. Oh, the humanity by daeley · · Score: 2, Funny

    Dang, dude. You wrote a rant over 1300 words long complaining about lack of documentation. Imagine if you and similar pundits contributed those words to the documentation of deserving projects.

    But, alas, whining is the quicker path.

    --
    I watched C-beams glitter in the dark near the Tannhauser gate.
  3. About documentation by fluor2 · · Score: 3, Funny

    The 10 laws of documentation of an GNU program:

    1. Add a 3-line FAQ for expected "bugs"
    2. Add "We need documentation authors" to README
    3. Wait for documentation to be written when you are finished with v1.0
    4. Delay documentation since it would break with the current v1.1 development
    5. You don't bother doing the documentation, since you've allready documented most in the source.
    6. When it works, you just publish the source and hope somebody else will do the rest.
    7. Make a website, create a logo and start having a nice time making design and stuff. When finally creating the documentation/index.html, just add Under Construction, since what you really want is a even better logo.
    8. Write some complex documentation, and hold back the real tutorials and publish them in a book.
    9. Spend some time with emacs, to finally understand that it sucks to write documentation when you have to think of line-breaks in a text document.
    10. Include an myfile.conf.example which you think will cover most questions anyway. Do forget on purpose that many lines need linebreaks at end of text, even if it's the last line. And also forget to add that TAB's are not supported in your .conf file.

  4. I have only one thing to say... by eviltypeguy · · Score: 2, Funny

    RTFM