views:

39

answers:

3

I have searched for a sort of system to match FLOSS projects with writers, and there doesn't appear to be any. This is aside from the few wiki manual projects out there, which I feel doesn't really give enough credit to the writer. Is this an unfilled niche, or am I missing something?

Looking willy-nilly for a mature enough project that requires documentation isn't the most satisfying of activities, and you really can't be sure that your efforts won't be in vain, unlike code improvement.

It seems like if you don't have a favorite project that you have deemed to be in need of documentation, then you are really wallowing through mud.

Searching with keywords like "needs documentation open source" doesn't really turn up anything either.

I'd like to hear from some FLOSS writers who have been through this.

+1  A: 

Debian has a missing(7) manpage, that has bug numbers and names of missing manpages that should be written.

You can also just discover that software you use (doesn't have to be favorite :) doesn't seem to be well-documented. (For example, nginx has in-depth Russian documentation: http://sysoev.ru/nginx/docs/ but the English version is somewhat lacking: http://nginx.org/en/docs/ -- if you wanted to write official English docs for nginx, maybe they'd be interested in integrating and maintaining the documentation.)

sarnold
+1  A: 

Is this some kind of...

The simplest criteria is whether the project has a corporate, involved sponsor. Even then, most of those have crummy docs.

99.99% of the FLOSS out there needs documentation. Whether the project is "mature" enough is a different story. It's simple enough to look at the activity level of the mailing list or the users.

Some projects have books written for them, but even those are lacking.

There's always room for more documentation on any project.

Just pick any project that you fancy.

Mind I don't know what motivates technical writers, beyond the obvious food and mortgages. Coders code for the challenge of the code, for wanting the tool. Most writers don't need to do that. By the time they learn enough about something to actually write about it, their "itch" is scratched if they just want to know about the software. If they're truly driven to write quality docs because they like to, then, hey, more power to them. But I've not encountered many like that.

So it's just hard to envision random writers wanting to pick up and document random projects. They need to have some other involvement in the project that's more than casual.

Will Hartung
+1  A: 

I'm a technical writer professionally. I've looked to contribute documentation to projects. It's not easy going. Most projects just aren't particularly good at identifying such needs and making them known (though a few projects, like Django, do flag things in their bug trackers for documentation). Other projects just don't have the community support for it. For example, I emailed a project list to make sure my plan to make some fixes to the docs wasn't duplicating effort; I was dissuaded from contributing entirely.

My recommendation:

  1. Find a small documentation error or omission in a project you use.
  2. Fix the problem.
  3. Submit your patch (by mailing list or pull request or carrier pigeon or whatever mechanism the project uses to get code contributions).

The response you get will tell you a lot about that project's leader or core of contributors' approach to new people and to docs in particular. Ideally, you be will welcomed and your contribution will be accepted or receive constructive feedback, but don't be surprised if you're ignored or turned away.

I know you asked for an efficient way, but unfortunately, there's no clearinghouse for documentation needs. At least for now, a lot hinges on how each project's community handles documentation.

ddbeck
All that said, I'd love to see something along the lines of GSoC that helped to pair technical writing students with mentors in free software projects. Many of my fellow technical writing students wrote for free for businesses to build up their portfolios. It seems like such a waste when so many projects do need docs.
ddbeck