How Do I Make This Hard to Misuse?
Posted Mar 31, 2008 21:31 UTC (Mon) by rgmoore
(✭ supporter ✭
In reply to: How Do I Make This Hard to Misuse?
Parent article: How Do I Make This Hard to Misuse?
what it means in the real world is that coders with limited understanding of the library as a whole go thumbing through the documentation looking for a gadget that does what they want, and then plug it in, all the while failing to realize that another gadget would have been a much better choice. ... The solutions to this are either (1) make developers understand the design of the libraries they use at a deep level, or (2) write libraries with a minimal but complete feature set,
I think that you're missing an important possibility: write really good documentation. Sometimes you really want a dozen gadgets, each of which is different from the others in some small but important way. That's a lot less likely to trip up your users if you:
- Group closely related functions in the documentation, so that it's easy for users to compare the different functions and pick the best one,
- Cross-reference the functions, so that anyone who reads the documentation for functionA also knows that there are closely related functionA1, functionA2, etc., and/or
- Provide a high level overview of the functional category, complete with a discussion of the differences between the functions and when you might want to use one instead of another.
I know that when I'm writing documentation for closely related functions, I try to do some or all of these. It's very helpful when coming back to use something I wrote a few years ago to find notes like "function_A does not guarantee that data will be written in any particular order. If output order is important, use function_B instead."
to post comments)