What is the standard protocol for editing documentation? It doesn't appear to be a wiki, unless you have to explicitly request write access in which I wasn't aware of that. The reason I ask is that there are many times where I've spent forever toiling over the documentation of some new library that I wasn't familiar with, because the documentation either provided no / insufficient samples, functions with very general names and one-liner documentation that says (for example) "runs the service". Which is pretty obvious when the function is called run, but no mention of the implications or what "running" even means. Other examples include lack of discussion over memory ownership (I spent 6 hours yesterday trying to trace down a memory corruption only to later find that in one of the many example programs for the library a single line comment that said "this causes X to take ownership of Y". If that had been in the documentation I would have spent 5 minutes tracing down the bug. So my point in all this is can the documentation be in wiki format, and as a fallback is there a way that someone other than a library owner/maintainer can edit it?
Zachary Turner wrote:
What is the standard protocol for editing documentation? It doesn't appear to be a wiki, unless you have to explicitly request write access in which I wasn't aware of that. The reason I ask is that there are many times where I've spent forever toiling over the documentation of some new library that I wasn't familiar with, because the documentation either provided no / insufficient samples, functions with very general names and one-liner documentation that says (for example) "runs the service". Which is pretty obvious when the function is called run, but no mention of the implications or what "running" even means. Other examples include lack of discussion over memory ownership (I spent 6 hours yesterday trying to trace down a memory corruption only to later find that in one of the many example programs for the library a single line comment that said "this causes X to take ownership of Y". If that had been in the documentation I would have spent 5 minutes tracing down the bug.
This idea sound slike a great one. I think a more liberal take should be done on such editing -- ___________________________________________ Joel Falcou - Assistant Professor PARALL Team - LRI - Universite Paris Sud XI Tel : (+33)1 69 15 66 35
participants (2)
-
joel -
Zachary Turner