For more content like this subscribe to the ShiftMag newsletter.

_ “Hello, my name is Inigo Montoya. You killed my father. Prepare to die.” _

Look at these three short, beautiful sentences and ask yourself whether there is something left to be desired.

Yeah, I thought as much.

They’re perfect because they strike the balance between being short enough not to bore you and driving their point across, just like Inigo drove his rapier through Rugen’s torso. This is exactly how your spikes should be. I mean, you shouldn’t drive your spike through anyone’s torso, but you get the gist.

Coincidentally (or not), this quote is from the cult movie The Princess Bride, which could be considered a fairy tale. But what does a princess have to do with such a technical term as a spike?

…what’s that? “What’s technical about a spike?” I hear you asking. My bad, I should’ve explained that I don’t mean sharpened sticks when I say spikes. So what do I mean?

What is a spike?

We’re, of course, talking about spikes in software development. Let’s skip the textbook definition of eXtreme Programming mumbo jumbo and let me explain it in the simplest of terms: it’s a process of discovery.

You have a problem you need to solve, but there are just way too many questions and unknowns. Sure, you could dive in head-first and attempt to resolve all the issues on the spot, but we all know how that ends. Been there, done that.

Spikes are meant to allocate some time for research and documentation of the problem you’re facing. The output is usually an article or technical documentation to which you and your team can later refer if (sorry… I meant when) you decide to tackle the problem. The term itself makes sense in the environment of agile development, but let’s forget all of that and simply call the process of discovery and its documentation a spike.

Before we go any further, I should probably warn you that I won’t actually tell you what methodologies to use to complete a spike – how to do the research, what to include, etc. This is a topic for another article.

We’re going to discuss how to make your spikes more memorable, easier to read, and simply better.

In this picture: A man is trying to make his spike more memorable.

Cool, now that we have that out of the way, I can answer another question you probably have.

What the hell do you mean by “spikes are fairy tales”?

You know exactly what I mean. Don’t tell me you’ve never trailed off to Wonderland when reading documentation. We all did it.

Studies show that over 90% of developers fall asleep when reading technical documentation. Source: trust me bro. That’s what spikes and fairy tales have in common – they make us fall asleep while taking us on a journey through made-up scenarios that we know can never be reality.

Okay, okay. I think I’ve been facetious enough. Let’s be serious for a second – it’s a real issue, and I’m sure most, if not all, of us have experienced it from both sides.

You spend time and energy writing something only to be asked over and over about details that are actually in there. Or you read through docs, and you just go, “Huh?” after every third sentence. It’s perfectly normal. We all get distracted when we read through something boring or when it’s so hard to read our eyes water up.

I know you’re just itching to write a spike right now, but it’s very important, and I can’t stress this enough, so I will use big letters. It’s VERY IMPORTANT to understand the scope and the purpose of your documentation. It’s amazing when you write a spike that’s easy to read, memorable and engaging, but it’s a complete waste of time when you spend two days perfecting it only for no one to ever read it.

Ask yourself these questions:

• Is this topic important enough?
• Will I or someone else refer to it later?
• Will it teach junior colleagues something new?
• Is the process as important as the outcome?

If you’ve answered nay to any of these questions, then don’t bother. It’s better to just do hardcore robotic documentation, which will at least be easy to navigate through. I mean it. Just do “this is the problem, this is the solution, have a nice day”.

Now that you’re able to identify what kind of documentation this article focuses on, we can go ahead and learn how to be able to write spikes in a more human-friendly way. But in order to do that, we’ll first have to understand what a spike is actually trying to achieve.

What should a spike achieve?

I’ve already said it a couple of times, but let’s repeat it again. The goal of the spike is to come up with one or multiple solutions to a problem, clear up all unknowns, and document the process. The last part is what’s important for us.

Many of us fall into the trap of simply writing out the outcome in a very factual and technical manner. This is great if you want to refer to it quickly, but it does nothing when others try to understand the thought process you went through. If others don’t understand your decisions, you will face questions like “Why did you choose this instead of that?”, “What if this happens? Have you thought of that?” or “I don’t understand how this is going to solve our issue; why are you like this? Why can’t you be normal like the others?”. Okay, maybe not the last one, but you know what I mean.

I don’t want to bore you too much but it’s important to understand how the reader of our spike should feel once they’re done reading it. Emphasis on feel. They should feel that they have the same or comparable understanding of the problem you have, they should feel that they know why you chose this solution, and they should feel awake and not asleep. The spike needs to introduce the problem, describe the research process, present the solutions, and evaluate them. It should answer all standing questions and it should be easy to refer to.

On to some actual advice!

How do we do it?

DISCLAIMER: I have no formal training in this. It’s just a bunch of stuff I thought made sense.

I wanted to refer to Inigo Montoya again, but it’s time to stop here. I’ve used his quote to hook you in but now I’m pretty much bending over backwards to make it fit our narrative. So let’s just retreat to a more simple structure we can follow:

1. The world building
2. The journey
3. The grand finale

The world building

First, you should introduce your readers to the problem. This is the world-building part—you introduce the characters, the world, and the basic premise of the story. It does not need to be too detailed; just use a few brief sentences and leverage references to tickets, diagrams, code, or threads on Slack. The key is to keep it simple without omitting any important information.

Your introduction should also outline the plot. In other words, you should explain why we need to solve this problem. Again, just a few sentences, nothing too fancy. This is the easy part. What you want to achieve is to have your readers understand the problem and why we’re solving it after finishing your introduction.

The journey

Now that everyone knows what’s up, it’s time to tell the story itself. You went on an adventure and you want to share this adventure with others. You want to make sure that people will see what you’ve seen, feel what you’ve felt and be able to understand your motives.

Remember, you’ve already been on this journey so you know exactly why it happened like it did. When you read your story, you know why you set fire to the forest, even though you didn’t explicitly say it – everyone knows that there are monsters in that forest! Well, that’s where you’re wrong. You have to realize that your readers did not have the same experience you did. Do not make the mistake of assuming that readers know what you’re talking about because chances are they don’t. Allow me to use an example from my own spike I wrote some time ago:

Let’s start by fetching n entries. We don’t need the values, we need the keys, so we could simply use the KEYS command, right? WRONG! I can’t count how many times I’ve seen “do not use KEYS in production!” plastered over the internet. Instead, the official docs point us towards using the SCAN command. It allows us to set the number of keys it will fetch, which we can set to n.

I could have just written, “We will use SCAN to get the entries”, but that would lead to questions. Why did you use SCAN and not KEYS?

From the style of this article and the short snippet of my spike, you can probably tell that I like to embellish stuff a bit. I would like to stress that you don’t have to do this. In fact, you should not overdo it and rather keep it too short than too long. It’s just my personal style, and wasting time on making something three times longer than it has to be is fun for me. Writing it like so:

Let’s start by fetching n entries. We will use the SCAN command, because official docs state that using KEYS is unsafe.

would have been perfectly fine. It’s shorter and much more to the point, which is absolutely a great thing. Remember, it should be short enough to be digestible in one sitting (in most cases).

The reason I wrote it like that and why I keep stuffing this fairy tale nonsense all over the place is to break the monotony of “lecturing.”

People can take only so many sentences of straight-up facts before their mind starts to wander off. By being funny (or at least trying to), you shock the reader a bit. Maybe you provoke a chuckle; maybe the reader cringes a bit. Both are fine – they’ve achieved their purpose, and the attention span has reset. Now, the reader is ready to consume more facts. Use jokes, pictures, whatever comes to mind. It doesn’t need to be funny, just not too serious. There is a delicate balance between just spitting facts and making a clown out of yourself, and quite honestly, it’s very hard to get right. But this is what it’s about – it’s about making the read interesting.

At the same time, make sure that your breaks don’t disrupt the flow of thought too much. It goes without saying that the process you’re describing should make logical sense. Start by building a knowledge foundation, exploring options, guiding through scenarios, and finally arriving at a decision. A good tip is to simply follow the process you went through because it’s natural. When you read a story, it doesn’t paint a picture of a bustling city, only to go back to the dangers of the road leading to it.

In this picture: A band of brave knights traveling to a bustling city.

Additionally, notice the style in which the few sentences from my spike were written. “We don’t need the values…” or “the official docs point us towards…”. We want our writing to be engaging, to make the reader feel like they’re also a part of the process. Writing it out like, “The values are not necessary. Keys will suffice. The official docs state that this and that should be used. Beep boop.” is incredibly monotonous and straight-up boring.

Another important thing to practice is assuming your reader will only have the most basic knowledge of the domain. Think of it as explaining to a kindergartner. You may think this would be an insult to your more experienced coworkers, but personally, I view it in the complete opposite way. Your goal is to explain something using the least complicated sentences so that your readers understand what is going on. Don’t shy away from using colors and animals instead of being overly technical.

But at the same time, don’t overdo it. Some parts will require straight-up technical terms or diagrams , and that is okay. Don’t try to substitute those with abstract concepts because that will result in no one being any wiser. What you can do, however, is ease your readers in by first explaining the thing simply and then fitting the more technical details into the framework you’ve built.

Last but not least – formatting is your friend. It’s much easier to read through text that is broken down into logical sections than through an unrelenting wall of text OF DOOM. You know how letters just kind of start to blend together, and you keep skipping lines? Yeah. Another thing you can use to a great effect is to highlight important parts of your text by using bold or colors. Just look at this article, and you’ll get the idea. Hopefully not the wrong one.

The grand finale

Finally, we get to the climax. This is what everyone is here for. The knight in shining armor had finally slain the dragon and rescued the princess. Everyone is happy and there’s fireworks everywhere. This is what your solution and results should look like. Don’t be afraid to use colorful pictures and striking formatting. Just take a look; which one do you think looks better?

This:

“We can put a smart balancer in front of our resolvers. That way the 3rd party service will have to know just one endpoint. The balancer will forward the request to our resolvers, which will load the data from our stretched database while caching the results. Because the result is not necessary for processing, we can notify the consumer asynchronously.” (yawn)

or this?

In this picture, A man is trying to make up a bogus diagram and failing miserably.

Which one was easier and more fun to understand? By the way, it’s excalidraw.com.

However, don’t make the mistake of thinking you can fairytale-ize this part too much. This is where the actual next steps should be and it’s important to remember that this is the part that people will most often come back to refer to. You can’t avoid technical details here, so don’t try to. ** But that does not mean you can’t make it as digestible as possible. It’s nice to have it funny and readable and everything, but **when people come back to refer to your solutions, they should be easy to find and understand.

Finally, remember to evaluate the solutions you’ve proposed. Personally, I would say that the best approach here is to keep it stupid and simple and do good ole pros and cons. Bonus points if you put it inside a fancy table and make the pros green and cons red.

Let’s sum it up

Screenshot this, put it next to your bed, and read it each time you go to sleep.

• Keep it simple, but don’t leave out important details.
• Keep it short, and don’t overdo it with storytelling. It should be digestible in one sitting.
• Make sure your readers understand the issue as you do. Guide them through the process.
• Leverage external references.
• Write in an engaging way – make your readers feel like they’re playing an important part.
• Assume that your readers have only basic knowledge of the domain.
• Break the monotony by cracking jokes or using media.
• Formatting is your friend – use it to drive your point across; important parts should stick out.
• When some part requires technical details, put them in.
• Spikes should be easy to navigate through, just stick to Introduction – Process explanation – Solution.

WTF did I just read?

That’s a great question. Quite frankly I don’t know wtf I just wrote. But if you got to this part it means that I probably did something right.

The point I was trying to make is that technical documentation does not need to be oppressively professional, dull, and boring. We can’t avoid it completely, but that does not mean we can’t make the reading experience better. Many people will make the counterpoint of this being a waste of time and energy, and I can’t say that they’re completely wrong. It’s not our job to write funny or beautiful stories, our job is to make machines do our bidding (while we still can anyways). But it’s also our job to do it in an efficient way.

Put on your corporate face and ask yourself this – what wastes more money – a developer spending three hours instead of one writing documentation, or six developers spending an hour each instead of 15 minutes trying to understand it?

If it’s going to be easier explaining your docs, why bother writing them at all? When you decide to spend the energy to write it, you might as well write it well.

Or, what the hell, you can just paste your documents into an AI chat bot and prompt it to improve them. What do I know?

Now, then, off to sharpen another spike!

The post Write spike stories like fairy tales appeared first on ShiftMag.