"At the very least, this demonstrates both respect and sympathy for other engineers who need to use an API. "<p>Sympathy?  As when an API is sort of hacky or kludgey or ad hoc?<p>"Often, it also correlates to a well engineered product underneath."<p>When I did Windows development I marveled at the amount and quality of detailed docs available for the platform.  In some cases the underlying each was well-engineered,  But there's no real  correlation.  The docs existed because a company really wanted people to develop for their platform.<p>Docs (or lack of)  say more about business than engineering.