Writing

The Importance of Clear Writing

In science, tech, or management, you influence people by writing things for them to read.

An essay helps you figure something out. Think of it as an idea graph - at each node, pick the most interesting related idea. Expressing your ideas also helps you form them. Writing them down forces you to think well.

Planning: Deciding What and How to Write

If you can’t envision the audience, think, “If someone had needed to give you this info 6 months ago, how should they have done it?”

Each section (and sub-section, recursively) should have its purpose.

If stuck on ordering, first write down ideas in random order, and then sort them. Sections need not be planned linearly. For example, the introduction can be last after knowing what it’ll introduce.

MUST and MUST NOT; On Writing Documentation

• Revise documentation, many times, and on separate days to catch confusing parts.

• Beware of ambiguities, e.g. X may not do Y. Refer to definitions, e.g. RFC 2119 .

• Put yourself into different roles, e.g. the person just looking for samples, the person who wants to read up on every nook and crany, the person who has no technical background etc.

But an effect can become a cause, reinforcing the original cause and producing the same effect in intensified form. The language becomes ugly and inaccurate because our thoughts are foolish, but the slovenliness of our language makes it easy for us to have foolish thoughts. The point is that the process is reversible.

Standard phrases already have rhythm. They are a convenient shortcut for lazy communicators.

Pretentious diction to make the banal appear profound, the biased seem scientifically impartial and sordid events masquerade as dignified.