The one thing I'd add is that, unlike most newspaper articles, technical documentation can be executable. I was so excited when I realized the implications of that I nearly had to sit down. (Yes, I live a boring life.)
I did a bit of that with the documentation to A/Bingo: the documentation is presented in a live demo, the formatted sample code is automatically composed from what I'm actually running (and thus gets automatically patched without me having to do anything special about it), and I copiously abuse my favorite Javascript effects (lightboxes, etc) to make the presentation flow better that linear text.
For example, often in tech documentation you want to focus attention on a portion of the code buried in a bunch of boilerplate. (Or maybe that is just those of us who write Java all day.) You can bold the bits you want to emphasize, or you can hide the boring details with Javascript and let only those folks who need them look them up.
My opinion is this is better than linking to a fuller version on another page, as it interrupts the user's flow less. It is also more readable than a few lines of bold text studded in the boilerplate, and more usable than omitting the boilerplate and producing code which doesn't function if copy/pasted.
The one thing I'd add is that, unlike most newspaper articles, technical documentation can be executable. I was so excited when I realized the implications of that I nearly had to sit down. (Yes, I live a boring life.)
I did a bit of that with the documentation to A/Bingo: the documentation is presented in a live demo, the formatted sample code is automatically composed from what I'm actually running (and thus gets automatically patched without me having to do anything special about it), and I copiously abuse my favorite Javascript effects (lightboxes, etc) to make the presentation flow better that linear text.
For example, often in tech documentation you want to focus attention on a portion of the code buried in a bunch of boilerplate. (Or maybe that is just those of us who write Java all day.) You can bold the bits you want to emphasize, or you can hide the boring details with Javascript and let only those folks who need them look them up.
My opinion is this is better than linking to a fuller version on another page, as it interrupts the user's flow less. It is also more readable than a few lines of bold text studded in the boilerplate, and more usable than omitting the boilerplate and producing code which doesn't function if copy/pasted.