The empty page: a horror story in three words
As I mentioned in my post about continuous delivery, my goal as a tech writer is to get as many SMEs writing their own documentation as I can. Getting people curious about documentation isn’t that hard, usually subject matter experts are passionate about their field and often eager to evangelize. But once they actually start trying to write content, many of them get cold feet. When I ask them why, I almost always get the same answer: “I don’t know where to start.“
Now, of course, that’s a completely normal problem to have. You have a good idea of what to cover, you’ve talked to the engineers and the subject matter experts, you’ve sifted through the hotline tickets to find the most common pain points, your homework is done and you’re ready to start. But you can’t. The page is blank, the cursor is blinking at you tauntingly, and the longer you stare at the screen, the sooner you start wondering if maybe you shouldn’t have become an ice cream truck driver instead. I still run into this problem here and there, and I’ve been doing this for the better part of a decade. The fact that the software we’re creating help for is fiendishly complicated doesn’t help.
Topics as a framework
Thankfully for me, seeing as I don’t drive and ice cream hurts my teeth, our content writing tool is topic-based. It doesn’t use DITA per se, since the goal of the tool is to be lighter, nimbler and simpler to use than an XML-based solution, but it’s definitely where the inspiration comes from. And good news, topics make for a great writing template!
A quick explainer : our tool, edc, makes several types of documents, also called strategies. How-tos, FAQs, glossary entries, theory-heavy document, what have you. Each strategy has associated topic types.
The basic topics that come with the product are About, Prerequisites, Usage, Example, Pitfall, Definition and Theory (you can create more if needed). They each answer a specific need or question. Now, if I’m writing a FAQ, I’m only ever going to need Usage and possibly About. If I’m writing a glossary entry, I only need Description. I don’t really need to think about it, I just need to drag and drop my topic, and since it’s a Definition, well, define.
For simple documents, restricting the list of topics stops you from straying too far from your intended goals. Longer documents are a little trickier, since you can’t use topics as a restriction, but you can still use them as a guide.
If you don’t know how to sort all that beautiful information you gathered, using the topic list in the order it is provided is a perfectly valid solution.
- About : what does the feature do? Why would you want to use it?
- Prerequisites : do you need to have done something specific before you use the feature?
- Usage : instructions on how to accomplish the goal of the feature
- Example : slap a screenshot of what the results should look like if you follow the instructions correctly
- Pitfalls : miscellaneous troubleshooting
- Theory : the sciencey bits, for users who like to know the maths behind how the feature works (most of our clients are geologists and geophysicists so we use that one surprisingly often).
This framework covers your basics fairly thoroughly and in an order that makes sense logically. None of the topics are mandatory, so if one of them is irrelevant to you, just omit it. The tool is designed for software user help, but you can absolutely use the framework without the tool. Allow me to demonstrate.
How to make crêpes, or topic-based authoring applied to daily life
About
A crêpe is a very thin type of flour-based pancake. It is usually served with a sweet filling such as jam or Nutella.
Prerequisites
Before you start, you need to gather the following ingredients:
- 3 cups of wheat flour
- 3 tablespoons of granulated sugar
- 2 cups of the milk of your choosing
- 3 medium eggs
- half a stick of butter
- 2 tablespoons of oil
- rhum or vanilla, for flavoring
- a pinch of salt.
Usage
- Melt the butter.
- In a large bowl, mix all the ingredients except for the milk.
- While whisking, pour in the milk slowly.
- Keep whisking until the batter is smooth and free of lumps.
It should be fluid but thick enough to coat a spoon. - Rest the batter in the fridge for at least 10 minutes, up to overnight.
- On low flame, grease a non-stick pan using butter or oil.
- Pour enough just batter to completely cover the bottom of the pan.
- Once the surface of the crêpe looks pale and set, flip it to cook the other side.
The cooked side should look pale blond to golden and uniform in color. - After 30 seconds, remove the crêpe from the pan.
The second side should look pale, speckled with small dark spots. - Reserve on a plate and cover with a clean dish towel until all the batter is used up.
Example
Here you can see the different look of the two sides of a crêpe.
Crêpes served in the traditional French style: smeared with jam or Nutella and folded into triangles
Pitfalls
The batter may still have lumps after whisking. Do not use the batter as is, lumps negatively impact the texture of the crêpe.
To remove the lumps, you can use a blender or pass the batter through a fine-mesh sieve.
If using a blender, allow the batter to rest for longer. Blending can whip air into the batter, the bubbles need time to rise to the surface and pop.
