Behind the Scenes - The "Dear Evil Tester" Style Guide and its Impact on my Testing

During the editing stages of “Dear Evil Tester” I started to write and maintain a style guide.

This was to help me track the ‘basic’ errors I found in my writing, and as an attempt to ensure a consistent attitude and formatting in the text.

Most books, and “Dear Evil Tester” is no exception, have a ‘conventions used in this book section’. This is a mini style guide which contains a set of small templates that I can use during the writing process. This section doesn’t go so far as to list the weaknesses of the writer, which is one reason for making it public. Whereas the weaknesses can be inferred from the reading of a style guide, so we keep it secret.

I’ve embedded the style guide below.

But first… a quick reflection since I will carry this approach forward into my testing.

I generally make a lot of notes when I’m testing. I do not always summarise them into a concise guide. I will now.

I’ll write down the:

• handy tips,
• obvious errors I commit,
• reminders of high level aims.

Previously I’ve relied on my archive of notes and ‘searching’ through them, which has worked well. But I think that the additional exercise of reviewing, and summarising, will help embed the knowledge in my head which might even cut down on the searching.

It should also make it possible to share with other people.

I know that we have tried to do this on projects through wiki’s but, they often fall into disuse. Partly because they are written to be ‘read’, rather than ‘remind’, so are often wordier than they need to be. Also they tend to be written for ‘others’ rather than for ‘ourselves’.

Having the guide for my testing, might also help ‘others’ spot weaknesses in my approach. For example, if I haven’t listed a shortcut/feature in the tools then I might be missing out on something that might help my testing. The guide might reveal that to someone more expert than myself.

I’ve had in mind to build these for each of my websites. When I do, this will also have the side-effect of creating a single page that I can quickly review for any obvious CSS or common JavaScript issues.

And now, the style guide…

Evil Tester Writing Style Guide

This is the ‘writing style guide’ to support editors for Dear Evil Tester.

But Alan, that’s you! Yeah, and I forget stuff. OK!

Sublime Tips:

• ctrl + shift + F - Find across all files
• F6 - Spellcheck

Publishing Tips

• Remember to check in to Version Control before starting a preview
• Remember to deploy to Dropbox before starting a preview
• Remember to close down PDF viewer, before starting a preview

Editing reminders

If you find an error. “Find across all files” and see if you find it again - if you do, fix it!

When reading from print, to find the file, use “Find across all files”

Writing Style

Worry less about the sentence structure. Worry more about the flow. Think. What would Norvell Page write? What would Lester Dent write? Do not model H. P. Lovecraft.

Is it a sentence? Who cares. Just make sure it looks like one. And reads like one.
But we’re not supposed to start with a conjunction!

And who said that? Was it someone who started a sentence with “however”? What would the author of the Bible write? (Hint: And in paragraph two, they started with “And”! If its good enough for God…)

But…

• If you have (brackets) and have punctuation outside the brackets (like this), then it is only outside if it started outside. (Having a full stop outside this would be bad.)
• Its vs it’s (remember: find across all files) - It’s wrong to write its, unless its thing is being described.
• Don’t worry too much about capitalisation, but at least make it consistent in each letter.
• PS. PPS. (Don’t make it a dotty abbreviation.)
• Capitals for Things,
  • at the very least don’t mix it. “exploratory Testing” would be bad.
• Chapter and Section Titles use Capitals
  • Letter chapters are written like sentences. Unless they have a Thing in it.
• For example, we will not write For Example. And we will still write e.g.

But what about the readers that know grammar?

Ha. They’re going to be annoyed however you write it. Write it for the masses.

Recurring Jokes

If you ever get the opportunity to make a joke about repetition then you should take it. Copy and paste a previous section of text again. Preferably the previous sentence or paragraph. Some people will get it. Some people won’t notice. Some will call the grammar police. Either way, much hilarity shall ensue. So if you ever get the opportunity to make a joke about repetition then you should take it.