Skip to main content

Slight of Hand

As the wartime slogan had it, careless talk costs much time in reimplementation and testing and ultimately late delivery of software that contains less than you wanted at a quality level of just-about-bearable and which will be followed immediately by a patch release, no two, no three patch, no four patch releases.

It's incumbent on everyone in a development project to share knowledge efficiently by getting key points across economically. If you're not comprehensive, coherent, correct and concise, you risk other people missing your point because they never heard about it, couldn't follow it, didn't believe in it or lost interest in it, and that leads inexorably to extra costs.

In that spirit, the meat in this post is that you should endeavour be as open as possible, full in description and slight in length. When these are in conflict, strive to remove the need for fullness. If you must be full, then structure your content accordingly.

Software teams are often dislocated in place but even if not they will be dislocated in time for some of the time. Documentation (including wikis, bug reports etc) provide a form of collaboration and knowledge sharing between the author(s) and the reader(s). When the readers are also authors it's a more involved collaboration and when a document is the primary mode of communication too there's greater need for completeness, efficiency and clarity. Like all collaboration there is cost and because generally there are fewer authors than readers, it's generally cheaper for the writer to pay up front.

Here's some of the things I try to keep in mind when I'm writing for work.

Dialogue vs monologue. In a conversation the listener can interrupt but on the page it's up to the writer to provide context. If there's insufficient context your readers won't know what you're talking about and it will cost them time and effort to divine it - and they might not get it right.

If you say the same things in multiple places you create a maintenance headache or a breeding ground for inconsistency. As the Dev team almost have it, Don't Rewrite Yourself. Instead cross-reference or provide hyperlinks when possible to give context.

Avoid anaphora with no obvious antecedents in the context. So "in the meeting it was decided that ..." might be OK for you and the attendees today but what about someone else next year? If it's not important that it was a meeting don't say. In any case, give the important information which is, e.g. "The CTO said today that ..." Likewise, "elsewhere" "above" or "below" should be replaced with a link to the place. Documents are dynamic so don't just assume the layout or structure will persist.

You can avoid the need to explain terms if you just don't introduce them. Use the standard name for the thing you're referencing and do so consistently. Try to avoid even changing its spelling or capitalisation because, to readers, differences raise questions. Don't create implicit definitions either - when you need a new name for something then be explicit, once, clearly.

If you're digressing, and the digression is useful but not relevant, move it to somewhere else and reference it.

Group related points together. They provide and reinforce context.

Don't describe something when you can easily show it and don't overshow just because you can. If you have log or other trace then use it sparingly. Show the key lines with timestamps and full error messages and provide the rest in a link.

Screenshots are good. When they're good screenshots. A verbal description that leaves an exercise for the reader is wasteful of a reader's time. If you have many readers, it's wasteful many times. A tight text and a screenshot with a red circle round the problem is cheap and useful.

Justify your conclusions, but as briefly as possible. Resist the temptation of pointing the reader at a starting point from which they could reason to the conclusion themselves, although do point to that starting point. If not, you're selling yourself short and your reader long.

Don't play your cards close to your chest. You're in a team and what you think is irrelevant, impossible or ignorable may be none of those things to someone else on the team.

Write short, declarative sentences and short paragraphs. Don't be afraid to restructure and cut what you've written before you commit it.

Use indentation, font styles, bullets, headers and other formatting when they're useful for explanation or clarity. Avoid them otherwise - they're just a visual distraction. Use tables or diagrams when they can compress or simplify  lists or prose. But apply the same principles to them as you would to writing - be precise and concise.

Sometimes you do need to write more, but in that case, structure so that the key stuff is first, like a journalist would. Key points up front; context and detail later. Try to avoid putting your intepretation in front of the facts. For example, start with the problem not with a question about how to implement one possible solution.

None of this applies to blog posts, of course.


Popular posts from this blog

Notes on Testing Notes

Ben Dowen pinged me and others on Twitter last week , asking for "a nice concise resource to link to for a blog post - about taking good Testing notes." I didn't have one so I thought I'd write a few words on how I'm doing it at the moment for my work at Ada Health, alongside Ben. You may have read previously that I use a script to upload Markdown-based text files to Confluence . Here's the template that I start from: # Date + Title # Mission # Summary WIP! # Notes Then I fill out what I plan to do. The Mission can be as high or low level as I want it to be. Sometimes, if deeper context might be valuable I'll add a Background subsection to it. I don't fill in the Summary section until the end. It's a high-level overview of what I did, what I found, risks identified, value provided, and so on. Between the Mission and Summary I hope that a reader can see what I initially intended and what actually

Why Do They Test Software?

My friend Rachel Kibler asked me the other day "do you have a blog post about why we test software?" and I was surprised to find that, despite having touched on the topic many times, I haven't. So then I thought I'd write one. And then I thought it might be fun to crowdsource so I asked in the Association for Software Testing member's Slack, on LinkedIn , and on Twitter for reasons, one sentence each. And it was fun!  Here are the varied answers, a couple lightly edited, with thanks to everyone who contributed. Edit: I did a bit of analysis of the responses in Reasons to be Cheerful, Part 2 . --00-- Software is complicated, and the people that use it are even worse. — Andy Hird Because there is what software does, what people say it does, and what other people want it to do, and those are often not the same. — Andy Hird Because someone asked/told us to — Lee Hawkins To learn, and identify risks — Louise Perold sometimes: reducing the risk of harming people —

Enjoy Testing

  The testers at work had a lean coffee session this week. One of the questions was  "I like testing best because ..." I said that I find the combination of technical, intellectual, and social challenges endlessly enjoyable, fascinating, and stimulating. That's easy to say, and it sounds good too, but today I wondered whether my work actually reflects it. So I made a list of some of the things I did in the last working week: investigating a production problem and pairing to file an incident report finding problems in the incident reporting process feeding back in various ways to various people about the reporting process facilitating a cross-team retrospective on the Kubernetes issue that affected my team's service participating in several lengthy calibration workshops as my team merges with another trying to walk a line between presenting my perspective on things I find important and over-contributing providing feedback and advice on the process identifying a

Testing is Knowledge Work

  The Association for Software Testing is crowd-sourcing a book, Navigating the World as a Context-Driven Tester , which aims to provide responses to common questions and statements about testing from a context-driven perspective . It's being edited by Lee Hawkins who is posing questions on Twitter ,  LinkedIn ,  Slack , and the AST mailing list and then collating the replies, focusing on practice over theory. I've decided to contribute by answering briefly, and without a lot of editing or crafting, by imagining that I'm speaking to someone in software development who's acting in good faith, cares about their work and mine, but doesn't have much visibility of what testing can be. Perhaps you'd like to join me?   --00-- "We need some productivity metrics from testers" OK. I'd like to help you meet your need if I can but to do that I'll need to ask a few questions. Let's start with these: Who needs the metrics? Is there a particular pr

Risk-Based Testing Averse

  Joep Schuurkes started a thread on Twitter last week. What are the alternatives to risk-based testing? I listed a few activities that I thought we might agree were testing but not explicitly driven by a risk evaluation (with a light edit to take later discussion into account): Directed. Someone asks for something to be explored. Unthinking. Run the same scripted test cases we always do, regardless of the context. Sympathetic. Looking at something to understand it, before thinking about risks explicitly. In the thread , Stu Crook challenged these, suggesting that there must be some concern behind the activities. To Stu, the writing's on the wall for risk-based testing as a term because ... Everything is risk based, the question is, what risks are you going to optimise for? And I see this perspective but it reminds me that, as so often, there is a granularity tax in c

Agile Testing Questioned

Zenzi Ali has been running a book club on the Association for Software Testing Slack and over the last few weeks we've read Agile Testing Condensed by Janet Gregory and Lisa Crispin. Each chapter was taken as a jumping off point for one or two discussion points and I really enjoyed the opportunity to think about the questions Zenzi posed and sometimes pop a question or two back into the conversation as well. This post reproduces the questions and my answers, lightly edited for formatting. --00-- Ten principles of agile testing are given in the book. Do you think there is a foundational principle that the others must be built upon? In your experience, do you find that some of these principles are less or more important than others?  The text says they are for a team wanting to deliver the highest-quality product they can. If we can regard a motivation as a foundational principle, perhaps that could be it: each of the ten pr

The Great Post Office Scandal

  The Great Post Office Scandal by Nick Wallis is a depressing, dispiriting, and disheartening read. For anyone that cares about fairness and ethics in the relationship that business and technology has with individuals and wider society, at least. As a software tester working in the healthcare sector who has signed up to the ACM code of ethics through my membership of the Association for Software Testing I put myself firmly in that camp. Wallis does extraordinarily well to weave a compelling and readable narrative out of a years-long story with a large and constantly-changing cast and depth across subjects ranging from the intensely personal to extremely technical, and through procedure, jurisprudence, politics, and corporate governance. I won't try to summarise that story here (although Wikipedia takes a couple of stabs at it ) but I'll pull out a handful of threads that I think testers might be interested in: The unbelievable naivety which lead to Horizon (the system at th

Testing and Semantics

The other day I got tagged on a Twitter thread started by Wicked Witch of the Test about people with a background in linguistics who’ve ended up in testing. That prompted me to think about the language concepts I've found valuable in my day job, then I started listing them, and then realised how many of them I've mentioned here over the years .   This post is one of an occasional series collecting some of those thoughts.  --00-- In this series so far we've looked at words and syntax. In both cases we've found that natural language is an imprecise medium for communication. We might know the same words and grammar as others ... but they will have their own idea about what they mean ... and even where we agree there is ambguity ... and all of us, the world, and the language are evolving ... all the time. Today we'll add semantics which, in a pleasing twist, is itself ambiguo

Leaps and Boundary Objects

Brian Marick  recently launched a new podcast, Oddly Influenced . I said this about it on Twitter: Boundary Objects, the first episode of @marick's podcast, is thought-provoking and densely-packed with some lovely turns of phrase. I played it twice in a row. Very roughly, boundary objects are things or concepts that help different interest groups to collaborate by being ambiguous enough to be meaningful and motivational to all parties. Wikipedia  elaborates, somewhat formally:  [boundary objects are] both plastic enough to adapt to local needs and constraints of the several parties employing them, yet robust enough to maintain a common identity across sites ... The creation and management of boundary objects is key in developing and maintaining coherence across intersecting social worlds. The podcast talks about boundary objects in general and then applies the idea to software development specifically, casting acceptance test

Personal Development

The other day I got tagged on a Twitter conversation between a couple of my colleagues, Ben Dowen and Dan Ashby , which ended with Ben citing me as an example: But there is a trap, in that a Dev who Tests, or Tester who codes both risk becoming Test Automators ... The counter argument is Testers who code can do as @qahiccupps does, and use and build tools to explore. A jumble of thoughts tumbled out as I read it and here they are, in no particular order. It is flattering to be mentioned but I'm far from the only person doing this. Maaret Pyhäjärvi   and Rob Sabourin are vocal about the value it can bring and go out of their way to tell and teach others how to get it. Ben is right when he says I use coding as a tool, and as a tool factory. It's a means to an end. Coding itself doesn't give me a lot of pleasure. Having created a useful thing gives me an enormous amount of pleasure. I am not a great developer. But then I rarely need to be.   Yes, I have made bug fixes that