Slashdot Mirror

← Back to Stories (view on slashdot.org)

Writing Open Source Documentation?

Posted by Cliff on from the open-source-needs-more dept.

An anonymous reader asks: "I'm an Open Source guy that runs Linux, and suggests Firefox and OpenOffice to friends. Now, I'd like to give back, but the problem is that I'm not a coder. So, how do I go about writing documentation, and what kind of projects should I look into? What are some stellar examples?"

3 of 92 comments (clear)

  1. Uhhh.. just do it? by QuantumG · · Score: 2, Insightful

    Have a look at any of the 100s of games and other applications written for the Linux desktop.

    Go to the Help menu.

    Notice the only thing there is "About".. which is really helpful when it comes to figuring out how you play this puzzle game.

    What that About box does tell you, however, is the name of the author. Contact that person, offer to write a help page, they'll tell you how.

    --
    How we know is more important than what we know.
    1. Re:Uhhh.. just do it? by bit01 · · Score: 2, Insightful

      You would like to think so but the reality is more likely is they will tell you get lost

      Nonsense, an insulting and meaningless generalization.

      The actual reality is that every developer is different, most developers enjoy the attention their projects attract and while they might not help a lot due to time constraints they are likely to at least point somebody like this in the right direction.

      ---

      You communist! Breathing shared air!

  2. For good docs, pretend you're a newbie; eg GnuCash by KWTm · · Score: 2, Insightful

    The manual that comes with GnuCash accounting program is not just a user guide, but a simple and easy-to-understand accounting primer suitable for the newbie who isn't sure why s/he would need to know about accounting in the first place. Depending on what you wanted to contribute --whether you want to be a prolific updater of man pages for semi-geeks, or focus on fine user guides for one project-- this may or may not be the type of example you want, but it's something that made the GnuCash program much more valuable for me.

    I think one valuable attribute to have as a documentation writer is to be able to see it from the point of view of the newbie. Know what questions they would have, and give examples. (One thing that bothers me about man pages is that many of them don't give examples.)

    --
    404555974007725459910684486621289147856453481154 in hex is "You sank my Battleship?"
    [GPG key in journal]