3 ms·
If you understand English, you can write documentation. The bar is a lot higher than that. You have to understand English and understand the functions themselv
by vacri 16y ago
If you understand English, you can write documentation.
The bar is a lot higher than that. You have to understand English and understand the functions themselves. Sometimes even getting bullet-point list of functionality out of devs is like pulling teeth - leaving you with nothing to document in the first place. Similarly an understanding of why something was designed a certain way helps angle the documentation more accurately.
Clean documentation is hard, and doubly so if you're not the person who wrote X module for OpenFoo.
- leon_ 16y agoAlso if you understand the project well enough to write documentation you have to have the ability to put yourself into a new user's position. Many people lack this ability and create just unusable docs.
- jwhite 16y agoAgreed. It's a hard skill even when you're trying consciously. One way to improve the situation is to actually give your draft documentation to a trusted user for feedback. I've been lucky enough to have an enthusiastic user in-house who has road-tested some of my documentation, and it's much better for the exercise.
- briancurtin 16y ago> The bar is a lot higher than that. You have to understand English and understand the functions themselves. In general, you're certainly correct. I was thinking too much about Python, where there's a strict but easy to follow guideline that all public APIs are documented, so the lowest level work has already been done. Because of that, there aren't a ton of places where you'd need a super deep understanding of the code in question to make a documentation impact. A lot of it is updating, removing, and reformatting. You'll see a lot more "reformat this paragraph as a table" issues than "write the whole doc for the wizbang module", the former being a fairly easy task.