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:
a. we defied some in-house developers working on other projects to a friendly programming contest,
b. we gave developers the option to run their programming race with or without documentation: just that they had to choose before starting which path they would follow. Half of the developers then did not use documentation, the other half did so.
Note: All six developers that entered the contested wanted to sit with the APIs documentation, but this of course was not enough to persuade our managers. So we asked half of the developers to go without the documentation, bribing them with a bigger price, which included chocolate chips.
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! :)
Pablo Varela
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.
a. we defied some in-house developers working on other projects to a friendly programming contest, b. we gave developers the option to run their programming race with or without documentation: just that they had to choose before starting which path they would follow. Half of the developers then did not use documentation, the other half did so. Note: All six developers that entered the contested wanted to sit with the APIs documentation, but thisFor a project with some obstinate managers, we plot and executed a simple but insightful scheme:
of coursewas not enough to persuade our managers. So we asked half of the developers to go without the documentation, bribing them with a bigger price, which included chocolate chips.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! :)