Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Yup, agreed. Creating and endorsing good documentation is an artform in itself.

Currently the barrier of entry is too high and I guess too few people are deep enough in twisted to explain all the why's of even a simple baseline example properly.

It's kind of a deadlock situation because without that lowlevel insight it's also hard to get confident enough to contribute high-level docs.



> Currently the barrier of entry is too high and I guess too few people are deep enough

Thing is, through checking out Django I realized you don't really need to be "deep enough" to contribute to that stuff. The thousand-cut effects applies, and when you're trying to make heads or tails of the doc, you're bleeding from these thousand cuts so you know and understand the doc's pain points. If doc contribs are first-class, then right as you understand the issues and what the doc tries to say, you'll be steered towards opening a documentation bug (and maybe even contributing a patch) for that part.

Maybe it's just doing to be a bit of wording, maybe it'll be a link or two to other relevant parts of the doc; maybe it'll be things you'll have figured through your sweat and tears, maybe something you'll have learned by asking a question on IRC.

But even as a beginner, you'll have added a little stone and made the doc slightly better through your current understanding. And it's enough.

I barely contributed to Django myself, but my first ever contrib was simply pointing out that the `now` tag's format character `n` produced an RFC 2822 date, not an RFC 822 one as written in the doc at the time. It was almost nothing, but it still very slightly improved the documentation for the next guy reading it, and it actually made me feel involved in the project. Even though I didn't have anywhere near the knowledge of the codebase to contribute to the code itself.

edit: and re the thousand cuts effect, that's the great thing about making beginners contribute: "old timers" don't notice or remember these small issues (which pile up), because they fill in he blanks or missing parts through their knowledge.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: