I had the pleasure of joining Tom Johnson in another podcast and one of the topics we touched on was that of so-called best practices. Today, I stumbled across this post in a thread about high-tech job interviews:
It’s hilarious to me that during the hiring process tech companies insist candidates know and follow best practices. And then when you actually work there you find out they actually just use a total disaster development process that’s held together with duct tape and a few nails.
— Melissa McEwen (@melissamcewen) June 25, 2018
On a personal note, it was actually a series of such experiences that convinced me to take my current job in academia.
One of the replies linked to this post: Best practices considered harmfull [sic] which summed it up as “Work out what your best practice is, work out how you can improve yourself.”
Unfortunately, by the time I got to this point in my feed, my blog reflex had been triggered, and here we are.
If we have to find our own best practices, what’s the point of having best practices?
Good question.
First, ask yourself, “Do you want a best practice or just a catchy slogan?” They are very different and serve different purposes. They are not interchangeable.
- Slogans are quick at the expense of precision and context.
- [Real] Best practices are precise and contextual at the expense of simplicity.
A best practice with some context can give you an head start by not making you learn everything through trial and error; a.k.a. the hard way. You can compare the context of the practice to that of your situation and maybe adapt it to work. If you’ve been following my earlier posts, you’ll know that I also encourage having a way to test that practice to see if it really is best (in whatever way that you define, “Best”).
Here’s an example
“Always wear your jacket” was something I heard frequently as a kid running to go outside. Sound advice, for most of the year, but during the summer, especially here in Georgia, such advice could literally kill you. Today the heat index was over 100-degrees, for example.
Best practice? 50-75% of the year, sure. For the rest of the time, it’s a really bad idea. So, “Always wear your jacket” is really a slogan. “Check the weather before you go out to see if you’ll need a jacket” is a best practice. Adding the goal for which it optimizes would improve it further, but I would be half-way to the neighbor’s house before my mother finished saying it.
A more constructive application of this might have been to explain the best practice and its context; when having a jacket was handy, when it could save my life, when it was a bad idea, how to tell them apart, and why it was important. Then just remind me of the case when I’d made the wrong choice, as in, “Bob, grab your jacket!”
Another example
“API documentation should have code samples,” or, its more extreme cousin, “API documentation should have ONLY code samples.” are slogans that I hear, occasionally. Sometimes, they apply. Other times, they can be a colossal waste of time and money. Time and money that could have been spent on something more useful to customers (i.e. more valuable to everyone). Which case applies to you? The slogan doesn’t even suggest there’s a consideration, so why would you bother to ask?
Pro tip: that it doesn’t suggest when IS the reason to ask.
Usually, the question of “when” is asked after a lot of effort has gone into writing (and later maintaining) code samples that are never used and customers are complaining about things that didn’t get documented as a result. Unfortunately, a common response to that is, “we need MORE code samples!”
Maybe you do, maybe you don’t, but since you’re following the best practices, how could you go wrong?
The context of this example is important. There are times when developers reading API documentation prefer code. In fact, there are so many such documentation use-cases that it’s easy to just simplify and say that it applies 100% of the time. There are times when pictures and text communicate better than code (often for higher-level conceptual topics).
Nevertheless, some developers claim their code/app/API doesn’t need documentation because the developer can just read the source code. The argument goes that the source code is always the most accurate representation of what it does, which is true. It’s just rarely the best way to explain it.
Converting that from a slogan to a best practice might look like, “To avoid hiring technical writers and to satisfy the smallest possible group of potential customers, time and money can be saved by not writing documentation and instructing customers to read the product’s source code.”
For some, I suppose, that could be a best practice.
Extending the “developers prefer code” argument to “just let them read the code,” illustrates another problem with unqualified and unbounded best practices: they tend to approach the absurd.
My favorite best practice disguised as a slogan
“CUT! CUT! CUT!” and its twin sister, “Less is more.”
The best practice version of this slogan is, “To enable readers to accomplish their task as efficiently as possible, know your readers’ documentation use cases, and don’t include any more content than they will need to accomplish the goal of their use case.”
“CUT! CUT! CUT!” is the slogan that resulted from the best practice that includes (at least) these steps:
- Know your reader.
- Know their use cases and goals.
- Know the use case(s) that would apply to a given topic.
- Know what the reader knows so you don’t repeat it, unnecessarily.
- Know the context in which the reader will read it.
- Write in such a way that takes all this into account
- Edit the result so it’s succinct and to the point (without cutting too much out)
Unfortunately, the reality is that there’s a lot of content floating around that is longer than it should be. Especially when the writing process stops at (or consists of only) step 6 . In those cases, trimming the content down (i.e. step 7) is probably necessary advice.
But, what if you’ve done all that work, including step 7, and perhaps even usability tested the content to add that extra level of polish (after all, you’re a professional who takes great pride in your work). Then “CUT! CUT! CUT!” is a bad idea and nothing anywhere near a best practice.
That’s because, “CUT! CUT! CUT!” ISN’T a best practice, it’s simply a slogan (or, perhaps, a chant).
In the previous example, the “let them read code,” is just “CUT! CUT! CUT!” taken to its logical extreme (which would make it a super best practice, right? NO!!!!)
Best practices, what are they good for?
Following a best practice can be productive, if the goal and the context of the practice align with yours. Because this information is not always present in the slogan form, make sure you understand them before you consider applying it to your case.
Here’s my recipe:
- Have a way to measure the results that matter. If you don’t have a way to test and measure what’s important to you, start here. A best practice (even one with context) isn’t a get-out-of-testing-free card, no matter how tempting it might seem, how urgent the need, or how convincing (or expensive) the consultant.
- Adapting the practice to fit your context. If the context or the goal of a best practice is not the same as yours, could the practice be adjusted or do your goals need some analysis (or both)? Maybe there’s something to learn from the best practice besides.
- Lather, rinse, repeat. When you have a way to test what’s important to you, a best practice can be a good place to start and then adjust to make it the best in your in your context.
It can be done, but it works best when it’s done deliberately with your eyes open.
If you want to read the source information that contributed to and inspired the content in this post, see my Useful Stuff.