I enjoy speculative fiction and “what-if” questions. I hang out at Worldbuilding Stack Exchange, where there’s always something to make me go “hmm…”.
My ideal is some of each — but that doesn’t have to mean separate doc sets. Good reference doc includes overviews at the top level and for individual packages/modules. If I only have API reference doc it can be hard to figure out how to get started; a decent overview covering how it’s intended to be used (not just what’s in it) and showing a…
Beautiful post, thanks. Kudos to Dr. Sagan for making such a difference in one student’s life!
Inspiration is all around us, if we but stop and take it in. As a child of the 60s I longed for space, longed to be up there — it wasn’t meant to be and I moved on to other things, but it never completely went away. Some years ago…
Think bigger. Having tech writers be first-class team members doesn’t just mean “let them hear what’s being discussed at your meetings”. Tech writers, at least good ones, understand user needs, usability issues, interface design, how what this team is doing might interact with other features, and more. If your tech writers aren’t participating in…
Interesting idea. I wonder if sending them to (their version of) hell goes too far in the other direction, though — in religions that have a “bad afterlife”, it’s usually pretty miserable. Do you really want to resurrect people just to torment them?
As a fellow tech writer, I concur — you’ve identified a lot of the things that make documentation challenging.
In a post on Meta SO I wrote about another aspect of the problem:
Regardless of subject, there are a few types of documentation, and when it comes to structure one size does not fit all. For…
Nice overview. One question: what’s with the partial image of the David statue in the picture of Neil Armstrong with the flag?
(BTW, your link about the shuttle crew surviving on the way down is about Challenger, but in your post it seems to refer to Columbia. You might want to tweak that.)
Have you encountered Heisenbug? These are the bugs that disappear when you try to watch them — e.g. the code runs just fine in a debugger or with extra logging turned on. Timing issues are usually at fault.
(I first heard it from a coworker in QA, though I believe it was not original to him.)