Jump to content
I believe there are several issues here that should spawn different conversations, namely:
1. Good API designs require good design documentation.
I have worked writing reference material and tutorials for very complex solutions that had poor design documents. Outcome: disaster. As an anecdote, developers leaving the team would leave information vacuums behind that no one could fill. Software improvement is based on comprehensive knowledge transmission. That is what documentation is for.
2. User documentation (programming references, for the matter) are integral to successful public APIs.
For a project with some obstinate managers, we plot and executed a simple but insightful scheme:
c. the games began. Each developer had to complete two tasks, one relatively simple (beginner level) and one relatively complex (expert level). The one condition: they had to use API calls to complete the tasks, without it being simple obfuscation.
Developers using the APIs reference documentation performed faster (completed the tasks in less time) and better (used higher-level API abstractions, specific for each task). A lot of other metrics where pointed out, such as better execution performance, neater coding style, fewer lines of code, etc.
I do not claim these are the most rigurous scientific data out there. Just that it convinced our managers, and that it points in some direction worth taking.
3. Documentation has a cost, as well as no documentation has a cost.
The most known cost-downsizing techniques in technical writing are shortening the amount of documentation, and reusing whatever documentation is written. Writing the documentation appropriately and precisely from the very very start is the only way to guarantee that less writing is taking place and most reuse will be attainable.
@Frances, you put your thumb where it hurts. And I love it!
@Anthony, you sound like a good manager. I just hope you had been in some of our projects! :)