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. I’ve noticed this when composing a post to ask why my code is not working....

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. How is the purpose defined? Maybe each question should be an answer to an implicit question. If stuck on ordering, first write down ideas in random order, and then sort them....

00. An Introduction to Writing; 01. Invention; 02. The Subject; 03. Classification and Order; 04. Beginning and Ending; 05. Expansion; 06. Momentum; The New Strategy of Style [Weathers, Winston];

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....