Hacker News Reader

Comment by tych0 | Hacker News Reader

I'm the maintainer of a small but reasonably active project, and the most frequent criticism I hear of the project is that our documentation sucks. And it's true! Several people have offered to write documentation, but I've never received any pull requests. I fix up the documentation here and there, but it'll never get where it needs to be without a focused effort by someone who really cares. (And it's not that I don't, I just have a long code TODO list as well...)

A lot of these technical writers have github accounts, where presumably they contribute to open source projects in the form of documentation. Does anyone have any tips for attracting such people to a project?

View on HN

I contribute to the documentation [1] for the Fluentd oss project [2].

I'm not sure how general my situation is, but in my case, a few friends were starting a company [3] and they had open sourced their log collector. Their initial team didn't have the writing skills / bandwidth to maintain great documentation [4], so they looked in their circle of friends to find a few people (including myself) with strong writing skills and a decent technical background (I work full time elsewhere).

The current workflow has developers writing the core / original documentation, which is then edited by more writing-centric people like myself (I edit heavily!).

One thing that might help, is to add the writer-friend as a committer to the project, even though he only writes documentation (this is the case for me). I think it helps with the obvious motivation issues, and also sends a message to the project at large that the project leadership deems documentation to be just as (or nearly as) important as the code itself!

[1] https://github.com/fluent/fluentd-docs

[2] http://fluentd.org/

[3] http://www.treasure-data.com/

[4] The CEO used to work for RedHat, which apparently treats documentation as a vital piece of their product. I remember him saying, "the documentation really is the face of a technical company".

I hear that. Riak docs used to famously suck-out-loud. It wasn't that the information was bad, it's just that no one had the time to devote to making them clean, consistent, or easy to navigate (ie. Info Arch).

Now we have some of the best NoSQL docs[1] around (clearly there's still more to do). A nice side-effect of cleaner navigation is that PRs to our repo[2] have increased dramatically.

[1] http://docs.basho.com

[2] https://github.com/basho/basho_docs

Reply on news.ycombinator.com