Exploration Through Example

Example-driven development, Agile testing, context-driven testing, Agile programming, Ruby, and other things of interest to Brian Marick
191.8 167.2 186.2 183.6 184.0 183.2 184.6

Tue, 16 Nov 2004

Hints for revising

If a sentence is unclear, do not fix it by adding more words. Fix it by splitting it into two sentences. Then maybe add a third.

If a paragraph is unclear, do not fix it by adding more sentences. First look earlier in the piece. Can you find a place to add a few sentences that will make the later idea clearer? Perhaps you can rule out an interpretation that will later cause confusion. Write text to head off the problem, then return to adjust the guilty paragraph.

If an idea or procedure is complicated, don't add more words explaining it. Add an example. If the example is too complicated, don't add more words explaining it. Precede it with a simpler example, then change the explanation of the complicated example to focus on what it adds to the simpler one.

If you use change tracking, turn display of changes off. You won't be able to make the new text read well if it's all mixed up with the old text.

After you change a sentence, leave it aside for a while, then come back and reread at least the whole paragraph that contains it. Then tweak the sentence to make it fit better into its environment.

How do you find what needs revision?

Can you turn that bullet list into one or more paragraphs? Bullet lists are, on average, easier for writers but harder for readers. They're easier for writers because you don't have to worry about transitions between one idea and the next. They're harder for readers because there are no transitions guiding them from one idea to the next. Will their eyes glaze over because you're not providing them with a sense of flow?

Read your text aloud. You don't have to write like you speak, but reading aloud changes your perspective. Awkwardness will jump out at you.

Reading aloud is one way to get some distance, to separate the piece from your memory of writing it. Putting it aside for a day or, better, a week does the same thing. I find that reading a printed copy helps me see things I don't see on a screen. Can you find other tricks? Richard P. Gabriel tells the story of one writer who would tape his work to a wall, go to the other side of the room, and read it through binoculars.

Print the piece with a wide margin on one side. Next to each paragraph, scribble a few words about the paragraph's topic. Now read the scribbles. Do they form a progression of thought, a developing story of explanation? Or are they more like a bunch of thoughts hitched together in any old order? If so, shuffle them into a better order. (Some people cut the paragraphs out and move them around; I usually draw arrows from where the paragraph is to where it should go. I suspect the other people do better.)

Sometimes you read a piece where a particular secondary idea or clever chunk of text seems to have undue importance. It's almost as if the piece were distorted to find a way to make that gem fit. That's usually because it was. The gem came first, the piece grew away from it, but the author forced it to stay. Ask what your favorite bit of the piece is, then throw it out - or at least consider how the piece would read if you dropped it. I find this useful to do when I get bogged down during writing.

(Inspired by about twenty years of writing badly, about ten of writing competently, and five years of getting paid to edit. Not inspired by any particular author.)

## Posted at 15:58 in category /misc [permalink] [top]

About Brian Marick
I consult mainly on Agile software development, with a special focus on how testing fits in.

Contact me here: marick@exampler.com.




Agile Testing Directions
Tests and examples
Technology-facing programmer support
Business-facing team support
Business-facing product critiques
Technology-facing product critiques
Testers on agile projects

Permalink to this list


Working your way out of the automated GUI testing tarpit
  1. Three ways of writing the same test
  2. A test should deduce its setup path
  3. Convert the suite one failure at a time
  4. You should be able to get to any page in one step
  5. Extract fast tests about single pages
  6. Link checking without clicking on links
  7. Workflow tests remain GUI tests
Permalink to this list


Design-Driven Test-Driven Design
Creating a test
Making it (barely) run
Views and presenters appear
Hooking up the real GUI


Popular Articles
A roadmap for testing on an agile project: When consulting on testing in Agile projects, I like to call this plan "what I'm biased toward."

Tacit knowledge: Experts often have no theory of their work. They simply perform skillfully.

Process and personality: Every article on methodology implicitly begins "Let's talk about me."


Related Weblogs

Wayne Allen
James Bach
Laurent Bossavit
William Caputo
Mike Clark
Rachel Davies
Esther Derby
Michael Feathers
Developer Testing
Chad Fowler
Martin Fowler
Alan Francis
Elisabeth Hendrickson
Grig Gheorghiu
Andy Hunt
Ben Hyde
Ron Jeffries
Jonathan Kohl
Dave Liebreich
Jeff Patton
Bret Pettichord
Hiring Johanna Rothman
Managing Johanna Rothman
Kevin Rutherford
Christian Sepulveda
James Shore
Jeff Sutherland
Pragmatic Dave Thomas
Glenn Vanderburg
Greg Vaughn
Eugene Wallingford
Jim Weirich


Where to Find Me

Software Practice Advancement


All of 2006
All of 2005
All of 2004
All of 2003



Agile Alliance Logo