on revising

Lately I found myself involved into writing.
And I have been often cought into the vicious cycle of revising my (or other's) text without really understanding how to do it properly and when to stop.

I want to summarize some of the advise I found on the web.
I put it here for me to find it again and share.

Let's first paraphrase the famous grook from Piet Hein:

THE ROAD TO WRITING?
Well, it's plain
and simple to express.
revise and revise and revise again,
but less and less and less.

I found an interesting post by Brian Marick.
(And [for now] I reformat it here for my own use. But I will revise it later ;-)

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

Automatically extracting bomb drops from the Blitz Bomb Census maps

I just finished Blackout by Connie Willis and I was wondering where she did get all the exact times when the air raids of The Blitz were happening.
I am curious because I was thinking that a timeline map would give a visual effect of the huge destruction and hard times the Londoners had to go through...so I googled for it and found the following:

• a nice research blog which uses the Blitz Bomb Census from The National Archives
• a blog entry from the Guardian about the first day - and data - of the Blitz over London.
   Here the source of info is the London Metropolitan Archives

Both examples show nice data visualization opportunities, but they both show how difficult it is to obtain data. Digital access to historical data could triggers a blossoming of applications!

Anyway I experimented with the little map from the first blog and wrote a little program using SimpleCV.

This is were I started from:

and this is what I got (without too much work, I must admit):

The code is quite simple and the parameters could be changed to get higher accuracy.

blz = Image("./sampleimages/the_blitz.png")
img = blz.copy()
dist = img.colorDistance(SimpleCV.Color.WHITE)
dist.dilate(2)

segmented = dist.stretch(240, 255)
blobs = segmented.findBlobs()
if blobs:
 circles = blobs.filter([b.isCircle(0.6) for b in blobs])
 for c in circles:
  img.drawCircle((c.x, c.y),
                 c.radius(),
                 SimpleCV.Color.YELLOW,
                 2)
 img.show()

wiki of the future?

Last weekend I have been watching, reading and playing around with Ward Cunningham's Smallest Federated Wiki. As usual he is a great designer and aims to simple, effective, understandable and useful tools! I particularly like the plugins idea (not new of course) and how easy it seems to be to add new ones, like support for MathJax:
Get inspired you too!

syntax highlight

The following example shows how to syntax highligh some snippet of code in a very minimalistic way.
I used it by symlinking to a file in the version control repo and name it in as the argument of
$('#code-area').load() and here it is:

  
  
  
  
  



Metacircular code highlighting
The following code is an highlighted version of this very page using
SyntaxHighlighter.


You need a decent modern browser to enjoy it.



  
  

metacircularity

I found and liked a very good summary of the 'Maxwell Equations of software' motto from Alan Kay in this post from Michael Nielsen.

It is nice also because it has running code inspired by all the gurus and books I like: Alan Kay, Peter Norvig, John McCarthy, SICP, Paul Graham.

Git and RSA identities

Here is the solution I found to be able to use git with a different RSA identity than the rsa_id default one.

My repo on github is logback-android and my user account is espinielli.
I did generate an SSH key as per github help and named it github_rsa:
$ ssh-keygen -t rsa -C "your_email@youremail.com" -f github_rsa

I then added the following section in ~/.ssh/config
# github for espinielli
Host github
HostName github.com
User espinielli
IdentityFile /Users/espin/.ssh/github_rsa

From within the repo directory (I cloned it before via http):
$ git remote add gh ssh://git@github.com/espinielli/logback-android.git

And finally I am able to use it like this:
$ git push gh master

LaTeX on Blogger again

My previous post about LaTeX  on Blogger reported that the solution described there did not work anymore...
Now I found a new solution based on mathjax.

So let's try it straight away with inline math, like the great equation \(e^{-2\pi}\), and with displayed math like the following:
\[ \left [ - \frac{\hbar^2}{2 m} \frac{\partial^2}{\partial x^2} + V \right ] \Psi
= i \hbar \frac{\partial}{\partial t} \Psi \]