Just thinking out loud here; the way I normally write posts (this one included) is I have a rough idea of what I want to say and I normally just start saying it, I might write a few key sentences or paragraphs and then work out ways to join them together.

This is a very quick process, it can also lead to posts that are longer than they need to be and potentially ones that veer off topic.

For some posts it isn’t a problem (like, I feel, this one) I quite like a conversational post that has the impression of being only slightly planned.

For other posts it might be beneficial to purposely keep them succinct, for example if I find installing a certain plugin wasn’t as straight forward as I would have liked, or my particular setup meant I had to jump through some hoops in a slightly different order to what the README file would suggest.

In these cases I would suggest perhaps we need to treat the post more like a body of code and write some unit tests for it, here is an example of what a post unit test might look like.

  • The post should describe the error message you might initially see.
  • The post should describe the steps to rectify the error message.
  • The post should describe what should be done if the error message persists.
  • The post should contain a screen shot of the file you need to click on.

Now we have this the challenge becomes how to get these ‘tests’ passing with as few words as possible (just like coding, we want to go green as soon as possible!)

Once we are happy our post completes the goals, it is time to refactor! We might find a slightly different order would work well, or maybe the terminology isn’t technical enough (or is too technical), we might even find a couple of introductory paragraphs would really work well. Just remember after every edit we should check the test spec we have written to make sure everything is still passing.

I like to refine my writing where I can, and if you’ve enjoyed this article you might like some of my other ones on writing.