Want to read Slashdot from your mobile device? Point it at m.slashdot.org and keep reading!

 



Forgot your password?
typodupeerror

Comment: Re:Um, no (Score 1) 211

by Jay Vollmer (#44751815) Attached to: Writing Documentation: Teach, Don't Tell
Um, yes, but...

Good documentation needs to be able to walk the line between being good enough and exhaustive. Nobody wants to spend a lot of time reading what they would consider pointless supportive text, but sometimes this explanatory thread is the best way to communicate the ideas involved. I'm a former high school teacher who has discovered that I love technical writing. I think that every teacher will agree that different people learn in different ways and through different modalities. I've been writing technical documentation for many years now, and I've always had the most success when I approach each topic explaining it in a way where I present the important 'get out of my way' details for those who aren't helped by supportive text, but also with these features tied together with an explanatory thread for those who are helped by this approach.

The time spent on any item of the agenda [of a finance committee] will be in inverse proportion to the sum involved. -- C.N. Parkinson

Working...