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. Anwyhere you like by LarsWestergren · · Score: 5, Interesting

    It is great that you want to contribute with documentation. A great program/framework/OS/whatever that no one can use because there is no documentation to be found is worthless.

    Sun has published a pretty good book called Read Me First! - A style guide for the computer industry. Covers "writing styles", legal guidelines, writing for an international audience, types of techical documents, and so on. Recommended. For a fun example of how NOT to write, read this page and see if you can figure out which sentences refer to the "old" bad way to do animations, and which sentences refer the new recommended way (the rest of the tutorial is pretty good though, and I really appreciate the time and effort people have spent on it - I just wish someone who knows more than me about Blender could rewrite that particular section.)

    Which project to contribute to - well, you had three good examples there. Just pick any project you are passionate about and comfortable using, try to think about what documentation you would have found handy when you was learning to use it. Start writing that.

    --

    Being bitter is drinking poison and hoping someone else will die

  2. Re:Uhhh.. just do it? by Timesprout · · Score: 3, Interesting

    Contact that person, offer to write a help page, they'll tell you how.
    You would like to think so but the reality is more likely is they will tell you get lost because since they didn't have the time/inclination to write the documentation in the first place they are unlikely to be able or willing to find time to hold your hand through explaining it all to you. Developers round here, myself included tend to attempt disappearing tricks when we see the technical writers heading in our direction.
    --
    Do not try to read the dupe, thats impossible. Instead, only try to realize the truth
    What truth?
    There is no dupe
  3. Consider posting a checklist by StephenNorthcutt · · Score: 2, Interesting

    It is great to give back to the community. I can help hook you up with the right folks if you want to a "how to" or develop a checklist or cheat sheet for an open source tool. We post them for the community to use as they will on http://www.sans.org/score, just drop me a note.