Ask HN: Have you ever written docs for an open source project you're new to?
So I've occasionally, upon trying to join an open source project, been told that the best way to get started was to write documentation for it. In fact, that if you're new you are a great person to write documentation because you know what is confusing.
I've been programming for about 8 years now and thought I would be able to do this by the time I graduated uni or had a few years in industry. That's happened and I've never actually been able to do this successfully and always ended up walking away in frustration. Has anyone ever written good documentation for an unfamiliar project? How do you go about quickly getting an understanding of the conceptual structure of the project from a high level?
2 comments
Not for an unfamiliar project. But I have written a bit, for projects i Use. In the past I contributed to the WordPress documentation because I was using it crazy.
Recently I contributed to the Chef documentation because I was using & learning it, and found a mistake in the documentation.
I would say if you want to contribute to the documentation, actually use the software (even just in a test environment) and look for holes in the documentation... little pain points like that really important thing they forgot to tell you about installing it, or additional things like how to back up the data.
Just like contributing code, don't try to write big parts on your own at first. Look for little things to fix; missing words, incorrect logic etc.
I would say if you want to contribute to the documentation, actually use the software (even just in a test environment) and look for holes in the documentation... little pain points like that really important thing they forgot to tell you about installing it, or additional things like how to back up the data.
Just like contributing code, don't try to write big parts on your own at first. Look for little things to fix; missing words, incorrect logic etc.
I never was in such situation but it seems it might be common practice, example: http://logback.qos.ch/volunteer.html