Documentation again

I got a few interesting responses to my last post.

Apparently I’m just a freak of nature who can sit down and write some fairly comprehensive documentation as a single task, whereas with coding, I often find it necessary (or at least beneficial) to take a break, go away and properly think about what I’m doing or trying to do.

People quoted reasons such as finding it hard to write documentation which is easy to follow, it just not being fun, reminding them of schoolwork, etc… Also, those with non-english nationality pointed out that they find it very hard to write documentation in (good) English and wouldn’t see as much recognition if it was only written in other languages.

I guess that answers my question. Still, my point remains, documentation is a very rewarding contribution in terms of direct feedback.

5 Responses to “Documentation again”

  1. Jeff Says:

    I also happen to like writing documentation, especially if it’s something that personally took me a while to accomplish. It’s rewarding to know that if other people run into the same issues, then they will quickly have the solutions laid out in front of them, as opposed to having to find them themselves.

    I think there’s a problem here though – I don’t know if people really understand the fact that they can contribute documentation. According to the Gentoo staffing needs page ( http://www.gentoo.org/proj/en/devrel/staffing-needs/ ), there’s no opening spots for any doc team. Everything seems to require experience with programming, and the dabbling I’ve done with Java is nowhere near enough to be able to contribute in this regard.

    Perhaps if it were more clear cut as to what people could write documentation for, and what Gentoo (or other projects) felt that they needed, more people would be willing to contribute.

  2. dsd Says:

    Jeff,

    You made two incorrect assumptions there.

    Firstly, you seem to think that you need to be a member of the Gentoo documentation project (GDP) in order to submit documentation. That is not correct. Anyone can do it, even non-developers, just submit your work on bugzilla, ideally in GuideXML format.

    Secondly, you have (mis)interpreted the staffing needs page. That is only a reflection of where contributors are needed the most. We still consider and recruit new developers in all areas as usual. We don’t have “spots” lined up like a company might, we are growing so fast that we need a high intake of developers to keep up, and due to the unrestricted nature of developer access, developers tend to start working outside of their main responsibilities too.

    I’ve filed a bug about the second issue ( http://bugs.gentoo.org/show_bug.cgi?id=96490 ). I can’t do that for the first until I’ve read over the GDP project documentation.

    As for your last point, Gentoo actually has exactly what you describe. I assume you have not come across http://www.gentoo.org/proj/en/gdp/roadmap.xml

  3. Jeff Says:

    I appreciate the pointers, and the bug.

    No, I had not seen that page before. That’s exactly the kind of page I was looking for; however, upon cursory glance, it seems this is only available by going to the Gentoo Documentation project page (which I’m pretty sure not everyone will know where to access). Might it be beneficial to link this page on the Staffing needs page, with a comment like this:

    “Note: If you are interested in contributing documentation to Gentoo, please visit the Gentoo Documentation Project Roadmap for more information.”

    I’ll point this out on the bug.

  4. Seemant Kulleen Says:

    Here’s the thing, Jeff. This is based on my personal experience and my experience in recruiting Gentoo devs (and documentation devs!) for the last 3 odd years. Daniel (dsd) is, in fact, a prime example of it. The experience shows this: those who are motivated to do things for the sake of doing them make the best devs. When dsd contacted me, he contacted me with a patch set to see if I would like to include it in portage (a gtk2 port of easytag). We communicated over bugzilla, and eventually, his work came so well and so frequent, it was easier to just let him have cvs and do the commits himself. And he’s proven to be, as many can attest, a really great developer. The thing is, he didn’t contact me with the notion of being a Gentoo dev (if he entertained such a notion, he certainly didn’t seem to have that notion as his primary motivation — his primary motivation was in making a patch he and others would enjoy). So, in short? You don’t need to be a gentoo dev to contribute. You just need to be motivated to do things that you like. Sooner or later, someone will recognise you for it :)

  5. Jeff Says:

    Seemant, I completely understand your point. Basically, the only thing I was really trying to say was that perhaps (and by this, I do mean perhaps :) users of Gentoo only believe that they can contribute to the project with code (even if they aren’t developers). Apparently, this is how dsd became an official developer in the first place. I was hoping to point out that it might have been unclear where and how regular users could contribute to documentation, making some users a bit hesitant to write a large tutorial or how-to only to have it RESOLVED LATER or something similar in bugzilla. However, I think this issue is solved, as the changes made to the staffing needs page definitely clarify my misconceptions.

    Thanks for responding, both of you :). I’m glad to use and be a part of (however small that part may be) this distribution, and it’s great to be able to discuss issues like this with actual developers.

Leave a Reply

You must be logged in to post a comment.