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

Comprehensive is not the same as user friendly, or well paced, or organized in a way that will assist new people learning.

I've seen plenty of projects that were exceptionally well documented. Every method and class had inline docstring documentation, every module has a separate module docstring block. 100% PEP 257 compliance was enforced as part of the CI tool chain... helpful but only after I was sufficiently knowledgeable about the way the project was being used to get any benefit from it. The the sheer volume of documentation meant that many people had written extremely terse explanations, often devoid of any of the contextual information that would significantly improve someone's understanding of how the code in question was be used.

Point is... The volume of documentation or the percentage of documented features, has no direct bearing on its usefulness to any particular user.



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

Search: