Expert Python Programming - Third Edition

Write in two steps

Peter Elbow, in Writing With Power: Techniques for Mastering the Writing Process, Oxford University Press, explains that it is almost impossible for any human being to produce a perfect text in one shot. The problem is that many developers write documentation and try to directly come up with some perfect text. The only way they succeed in this exercise is by stopping the writing after every two sentences to read them back, and do some corrections. This means that they are focusing both on the content and the style of the text.

This is too hard for the brain, and the result is often not as good as it could be. A lot of time and energy is spent on polishing the style and shape of the text before its meaning is completely ...