Fair, but I still think the vast vast majority of people consume documentation 
online. So it makes sense to bring the contribution interface there.

And of course, the best would be if we could get the library authors themselves 
to write docs. I try to document mine as well as possible (although sometimes 
only in doc-comments which aren't exported anywhere). But the fact of the 
matter is that writing good docs can be hard. Same goes for tutorials. So I 
believe the one thing we can do which will have the biggest impact is to lower 
the bar for being able to contribute. I've many times had to go poke around in 
source code just to figure out how to do something, and how many times have I 
ended up documenting it in the docs of the procedure? Barely ever! If there was 
a blinking cursor in a "Add your own sample" field though? I think I'd be much 
more likely to write down what I've discovered.

Of course these changes wouldn't magically make their way back into the 
documentation in the repo, so maintainers would have to check the hosted docs 
for public input before updating the repo docs. And if we auto-hide comments 
when the version number increases major version then maybe we can even get 
people to be more consistent in versioning their packages :)

Reply via email to