I'm taking Joel's suggestion to heart and will be trying to write something engaging, funny and fun to read.
I have been recently inspired by why's Poignant Guide (what happened to that guy btw?), and while I am not nearly as talented, I do actually exist. Have you guys seen any other examples of great and interesting docs you'd care to share?
I'd be careful here. If it ends up being not engaging, not funny and it's not really fun to read, then you'll end up with documentation nobody will read it. Those that do might not take it seriously.
I'd stick with accurate, to-the-point and concise documentation.
While it's good that you are proud of your work and you would like to see it reused, unless your title is something like "Chief Executive Dictator", I doubt that just writing excellent documentation will get your code noticed.
I would suggest creating a brief, high-level overview of the benefits of using your code over other approaches. Think of it from your audience's perspective and try to answer their question of "How will this help me?" If you can get buy-in and others are as excited about your code as you are, then they should be less hesitant to read the nitty-gritty details of the low level documentation.
I think this particular piece of advice from Joel is misguided. Unfortunately, very few of us are as funny as we think we are. (In fact, I think Joel is a pretty funny and engaging writer in general, but for some strange reason his example "funny" spec is more annoying than funny.)
For an example of engaging documentation, I like Dive Into Python. It's well-written and well-structured, and the author knows who his audience is.
The best things you can do to make your documentation engaging are:
[All documentation] Figure out who you're writing for. The answer is not "everyone" or even "all technical people" in your organization.
[All documentation] Get yourself a copy of Style: Toward Clarity and Grace and load the entire book into your brain. :)
[API documentation] Be sure to keep in all the things that API reference documentation typically fails to include. What is this thing? Why should I use it? Are there any caveats I should know about? What are the typical/expected ways to use it? What are the bad/pathological ways of using it? Finally, provide one or more full-fledged examples that exercise your data access layer to do something non-trivial.
lol,,, just above your post there is an ad with book of author worth mentioning when it comes to good and fun to read tech books , Steve McConnell his name...
I'd stay away from comedy. People are usually going to the documents for information not a punch line. If they are under the gun your comedy could be very insulting and frustrating. I would stick with empathy above all else. Imagine yourself as someone who has a deadline and not enough time to finish, or, imagine yourself as totally confused.
Then write your docs.
Your users (developers in this case) will love you for it, despite what the pundits say.
Django documentation is the best documentation I found so far