Five factors to consider when writing

This posting does a great job of dissecting some documentation on database design to illustrate how not to write a tutorial or an expository article. The five points listed in the posting really sum up what makes good technical writing.

The one point that’s easy to overlook is number 2: know when to stop:

If you’re writing a primer then keep it simple (stupid). By all means hint at greater complexity (in fact you should), but do it as an aside and don’t introduce new terminology that not all of your audience will know.

If you’re writing something for a more advanced audience then you will need to assume some prior knowledge. Only the very best writers and teachers have a hope of explaining advanced complexities to neophytes, and most of us neither write nor teach anywhere near well enough to try that.

This work is licensed under a Creative Commons Attribution 4.0 International License.