Where parallels cross

Interesting bits of life

Have you editing to do? Edit a little, edit every day, and let Emacs be your coach!

Too long; didn't read

Do you need to edit a piece of text that is hard to read? Have you to write something and you are afraid it will turn ugly? Writer-word-goals (wwg) now helps you making text more readable.

The problem

Writing is hard. You try to share your ideas in a way that others can understand. Every time I write something though, I get carried away. The more I write, the more complicated it gets. The more complicated, the less readable. At the end of my writing session (after the 1k words wwg pushes me to write), I have some ideas written down. And I have also some new edits to do. For that I will read and reread until it feels right. That is not great, because I cannot track my progress.

The question is: can my editor help me with that?

It is a problem indeed

It is funny, because this do&review is a pattern. In software you may get carried away by the code, and forget users' needs. Designers follow the beauty of their products and forget to make them easy to use. Even architects put the look of houses before how livable they are. (Stewart Brand tells a lot about architects in his book How Buildings Learn.)

It seems that we put aside the central features in favour of minor ones.

I think our tools can help us reminding ourselves what we are doing things for.

How cool would be if I can see readability while I write? I would like to see in one gaze that the following two sentences are more and less accessible.

An incredible amount of time of ours is spent in less relevant efforts. Really, we waste too much time in details.

If I could see that the first is less readable, I could change it when I have fresh in my mind what I wanted to express.

Would this be even possible?

And there is a solution

It is possible! I tested this myself "on the road". I wrote an article and got it published. This was my first writing gig. I used wwg to write the contents and I submitted. They aim for great content, so an editor checked my work. She reviewed, adjusted and asked me to clarify certain parts. At this point I had already wwg working for editing. So I rewrote the unclear bits while "seeing readability". She accepted them! No comment was surely a good sign. Now, I thought, I may be onto something.

So what did I do? I had already worked on something that did not lead me far. I am a happy user of writegood-mode. Some time ago I proposed an on-the-fly readablity score. The problem with that is it displays you the score while you write. Again: or you write or you read. Doing both is hard. As hard as writing and editing at the same time.

The scoring comes from writegood-mode. The mode uses Flesch–Kincaid readability tests. In essence we score sentences according to how long are the words and the sentence that contains them. The algorithm is simple. For that reason it does not work in all cases. But in most ones it does magic!

Note they made this score for English. In other languages the score my change.

Let me show how it looks like!

The green lines are easy. The yellow a little bit difficult. You want really to fix the red ones. In the example you can see all of those. Note how the red one contains a link. As I mentioned, the algorithm is simple, so false-positive are likely. So use this mode with a critical approach, not blind faith.

The view is available in two flavours: scoring by sentence (wwg-score-sentences-mode) and paragraph (wwg-score-paragraphs-mode). You may want a paragraph view for longer pieces of text.

Now comes the pretty cool bit. If we can quantify how easy a text is to read, we can also set goals!

Imagine you get this long piece of text to edit. You can now say: "I want to make this at least 20% easier to read". Then you "see readability" and choose the part of text to edit.

Now you can start this editing session with wwg-editing-mode. It does exactly that. It asks you to choose between three levels of editing: Easy, Medium or Hard. Then similarly to wwg-mode, it tries to keep up your morale by complimenting your progress. When you finish it, your text is easier to read!

Note: the highlighting may have some hiccups if the first sentence in the file does not end by a dot. I am going to patch this as soon as I have some time (I also accept PRs!!). I thought to share it early because it is too cool to keep it all for myself!

Conclusion

So do you have to write work emails? Do you have to review the homework of your students? Are you writing the next Harry Potter? Grab my wwg and make your life a bit simpler!

Happy editing!