Terror of the blank page: starting a new documentation project
Catherine Heath | April 18, 2019
Whether you’re a seasoned technical writer, or someone who is new to writing documentation, the terror of the blank page is not something to be taken lightly. Of course, it's hard to begin anything new, but following a process might make starting new documentation projects easier.
This guide contains both actionable techniques and inspirational tricks to help you get started in defeating the blank page. By the end of this post, we want you to feel much more confident when starting a new documentation project.
“All we have to decide is what to do with the time that is given us.” – J.R.R. Tolkien, The Fellowship of the Ring
1. Focus on the end goal
What problem is your documentation trying to solve? This question is a really useful tool for Minimum Viable Product in general, but for documentation it's also true. Here are some possible problems you might be tackling:
- Are you trying to reduce support burden?
- Make sure your employees are consistently following the same steps for tasks?
- Make sure people know who the correct SME is for something to reduce wasted time?
Sometimes, breaking your documentation MVP into these kinds of problem-solution sets lets you prioritize which portions of your documentation project to tackle first.The best way to begin is to begin at the end.
By focusing on your end goal, you train your mind to aim for a target and naturally imagine ways to overcome any obstacles. The end goal is your final project, whether that be your knowledge base site, PDF guide, or anything else.
And also, how many pages or words do you think you might need? What should your customers be able to do better as a result of this documentation?
2. Make your reader the hero
In all forms of writing, you must start with your user. What do they need? What is the most important task to tick off the list?
“Your audience is one single reader. I have found that sometimes it helps to pick out one person-a real person you know, or an imagined person-and write to that one.” ― John Steinbeck
Putting your reader at the center takes the focus off you and what you want. Your task becomes about better serving your reader's interests, and increases your chances of producing quality documentation.
3. Aim for Minimum Viable Product
Perfection is the death of productivity. If you aim for perfect, your project will never be done.
Unless you’re exceptionally lucky, you won’t have the resources to document everything. We’ve already covered Minimum Viable Product in your documentation and the importance of documentation triage. Aim for the least documentation you can produce for an acceptable product, and anything more is a bonus.
A Minimum Viable Product for your documentation could be as simple as a list of FAQs. Your FAQs can then help you start building out your knowledge base categories, or at least become a straw man that your team could provide feedback on. Your aim is to get momentum going.
4. Come up with a structure or outline
All complex projects can benefit from creating a basic structure. It’s like a line that you hang your clothes on. Without your clothesline, your clothes will just end up in a heap on the floor.
The structure helps your project take shape and keep everything in order.
The first part of structuring a complex project is to break it down into smaller chunks. Your top level categories can be broken down further into subcategories or subtopics. If you don’t have many topics within a category, perhaps it can be merged with another category.
Your categories should be arranged by level of importance. Your top level categories are the main features of your product or service. As you descend lower down in your nested categories, the topics and categories become more granular.
Make a mind map
Sometimes it helps to switch mediums and view your project visually rather than linguistically. This is where a mind map can come in handy – remember those?
You can use good old-fashioned pen and paper, or fancy software tools, but whatever you use make sure you map out the overall structure of your knowledge base. This will help you see how the information flows and the different parts connect together. If you prefer, use post-it notes.
Using Trello or Asana could be another good way to visualize your documentation project. Doing it this way can help you see what’s missing, and also help you see your project more objectively.
People are most engaged when you’re telling them stories. Stories help us to understand something that might otherwise be outside the realm of our experience. It’s what keeps us reading page after page.
Including some use cases can be a great way to bring your documentation to life – real-life examples of other people using your product. Your stories can also relate to your user journey, and making sure you begin your documentation where your user starts their story. This can include Getting Started documentation, for example.
Every page is page one
Every page is page one is a content philosophy by Mark Baker. It essentially means making sure that any page your user could land on in your website is "page one". The user can start anywhere and still make sense of your content.
Structure your content so that no matter what page your users land on, the documentation makes sense. Include a liberal dose of links so your users know where to go if the content isn’t for them.
5. Gather existing resources
Like we just mentioned with the templates, have a hunt around for anything you already have that could be useful.
It’s highly likely that your product or feature will have some existing documentation unless it's totally brand new. It could take the form of an old knowledge base, Slack chats or threads between team members, or some other kind of internal document used by your team.
This tip also falls under the umbrella of not reinventing the wheel. If you can improve on something that exists rather than creating something new, do that instead. It takes much less effort.
Existing resources could also include inspirational knowledge bases or documentation made by someone else entirely. Of course, copying is never a good idea – but there could be some best practices to learn from.
6. Test first
Whatever you’re documenting, make sure it works first. This means trialling the product as though you are in your user's shoes. If you’re one of the people who made the product, this step is even more important. You need to gain some perspective on your work, and identify more closely with your user instead of as the designer, product manager, or developer.
The same goes for your documentation. When you have a working documentation product, test it out on your team, and ideally on your users. If you find some things that aren’t quite right – and you always will – set up a process to review the documentation and redraft.
7. Use templates
There’s no sense in reinventing the wheel every time. When it comes to any new project, templates are your friend.
If you don’t have any documentation templates yet, perhaps make creating templates one of your first tasks. We’ve published a great post on documentation templates with examples.
Sometimes, making a template is the best way to conceptualize a new project – especially when it comes to one containing many pages of relatively similar content. You can make templates for an individual documentation page, or your knowledge base as a whole.
8. Product feedback loop
Docs don’t exist in a silo, but are part of what constitutes a finished product. That's why your documentation should be part of the product feedback loop.
You need the feedback you gather on your product to be acquired continuously. If there is a problem with your documentation, it should be fed back into the same team designing your product.
And don’t forget to feed back to customers when you’ve fixed any problems with your documentation or product in order to close the loop.
9. Make it fun
When you find a task fun, you are intrinsically more motivated to do it. Writing documentation can be fun! If you have room to make your documentation a little more fun then go for it.
Making it fun could be including a cute character in your product use cases, or using funny GIFs when gathering documentation feedback from your team.
What ever fun means to you, remember to keep it accessible though. Pay attention to accessibility issues, such as people using screen readers, or people who aren't reading your documentation in their first language.
A note on active voice
Think about the style in which you will write your content.
All of your content should pretty much be written in active voice unless you have a reason not to use it (perhaps in your reference documentation). This step is all part of making your user the hero.
Active voice is where you place the emphasis on the actor, or what is technically known as the subject, of your sentence.
Consider this first sentence:
- The button was clicked by the user
The sentence is written in passive voice. Emphasis is placed on the object (the button) rather than the subject (the user).
And now for the next sentence:
- The user clicked the button
It’s written in active voice. Emphasis is placed on the subject (the user) instead of the object (the button). Your user should always be at the center of your documentation.
Whomever said starting a new documentation project was easy was wrong. But it can be done – and it can be fun! We hope you've learned something from this list of techniques to help you overcome your fear of the blank page.