: Re: Should creativity or eloquence in a technical document be removed during review? I am working on churning out some technical documents, which are similar to a colleague's. I've copied some sections

@Speyer920

Vote Up Vote Down

This is a supplement to this answer.

Readers, especially technical readers, notice small variations and especially inconsistencies. If you talk about "removing" a resource in one place and "deleting" it in another, some but not all readers will think that's two different operations. This problem is amplified if your documentation is translated into other languages, because now both the translator and the reader have to interpret your subtle variations.

You can minimize this confusion by consistently using the nouns and verbs already in use in your documentation set. (When something is different from a similar-seeming one, call it out explicitly.)

This does not mean that there is never room for humor or even whimsy in technical documentation. If it is not unusual in your domain, you can sometimes be more creative with your examples. Never do this at the cost of clarity, but, for example, you can do this if you need to show some sort of user workspace and the actual content doesn't matter. If you're showing how to lay out a circuit board and your audience is expected to be geeky, it's not wrong to name the project in the screenshot NCC-1701-replicator instead of circuit-2. But don't do it if there are 500 examples in the documentation and you're just changing this one; be consistent in your style throughout the documentation set. I've found that "whimsical" examples are best reserved for shorter, less-formal, stand-alone documents like blog posts and use-case descriptions.

(0)

Login to post a comment!