Scribbling in the margins

Reference books, like “Java in a Nutshell” are so yesterday! We should be downloading secure digital content which augments our development environment. Most “nutshell”-like books are just annotated reference manuals some comments and examples in additional to the raw reference material. Well, I’d like to have my reference material hyperlinked and embedded in my development environment so it’s available in context, and therefore I’d also like the additional commentary to be embedded in my development environment too. Sun might supply the raw API documentation, and then third-parties like O’reilly could supply useful annotations. But let’s not have it on paper …

Now I want electronic margins to scribble in. Why is API documentation usually treated as read-only? I’m much more efficient when I’m using a highly personalized development environment. But most development environments won’t let me scribble on the API docs. It’s like the system assumes that the docs are the pinnacle of perfection and therefore don’t need to be altered. I can imagine that the margin notes from an experienced programmer would be worth their weight in gold.