10 lessons we learned from building a brand new documentation site
We were standing at the end of a road. Years of unstructured documentation was catching up to us. It was a matter of letting our documentation site collapse and form a super-dense black hole that would threaten the very existence of our planet, or initiating a major reboot project. After some contemplation, we chose the latter option. Here we have collected some of the insights we gained from this experience. So before attempting to do any of the below at home, please learn from our mistakes success story.
Grab a cup of coffee, and let’s get into it!
Background
Our company, Atomia, has been around since 2009. Our main product is a software suite for web hosting providers, which as you can imagine is one of those things that definitely need plenty of documentation. Over time our software product has matured and grown in scope. However, in retrospect it was obvious that our documentation efforts didn’t quite keep pace with our software development. We decided to start over with a new documentation site and structure (for the sake of our planet’s safety).
The ten commandments
There’s a lot to keep in mind, so here’s a quick overview of what we’re going to go through:
- Nail down who your users are
- Define your goals and set out a project plan
- Get a moral buy-in from everyone in your company
- Carefully define your documentation process
- Have clear responsibilities
- Set a deadline and milestones
- Embrace consistency
- Track your work to follow the progress of the project
- Collect feedback
- Be prepared to change direction
Now let’s really dive in, shall we?
1. Nail down who your users are
Why? Duuh, this is crucial for information architecture! Even the best-written piece of information is useless if it makes no sense to your user.
Cups of coffee required: A plain cup of coffee will do if you already know your user. Otherwise, brew a whole pot and do your research!
Define your users’ needs
We started the project with defining our user. Who would be using our documentation site, and what were their needs? We thought of when and why our users needed documentation. Was it during the startup phase or when performing certain tasks? Or was it out of curiosity to get to know our products and to see what our company had to offer? We considered how this would affect the way people searched for information on our site. The information most users needed had to be the easiest to find.
In our case we had more than one type of user, so our structure would need to take this into consideration.
Guide your users
With the help of simple mockups we tried out different structures. First we sorted our documentation based on common major tasks such as Installing our software, Configuring our software and Using our software. Then we structured the information by our different user groups: Developers, Administrators and Support. We evaluated the benefits of the different approaches.
Above, an early mockup of what belonged where.
We wanted to guide our user not only through the task at hand, but also toward what they should do next. We considered the workflows our customers experienced with our product and how to lead them through this process. You never want your users to feel like they don’t know how to proceed.
This is incredibly important to get right. In fact, we ended up with a big shuffling act about a month into the project because we hadn’t done this as carefully as we should have. Lesson learned!
We ended up with a structure based on documentation types:
- Manuals
- API documentation
- How-to’s
- Introductory information
Consider the level of knowledge that your users have
You always need to consider the level of knowledge that our users have. We needed to present information to people with vastly different roles, so every piece of documentation needed to take its intended audience into consideration.
Since many of our site’s users are new to us and our product, we needed to simplify the documentation that was of interest for this group. To make it easier for people new to our product we also created a dictionary in which we listed and described all commonly used terms on the site.
2. Define your goals and set out a project plan
Why? Well, this type of project can easily grow into a humongous monster. The solution is called planning, planning, planning. Make sure you have a clear strategy before you start creating anything. Measure twice, cut once!
Cups of coffee required: All the coffee you can drink!
Analyze the current situation and think things through
To get a clear view of the conditions that affected our future documentation site, we analyzed our goals with the project. We also kept in mind the site structure draft to ensure that it wasn’t conflicting with the conclusions we came to. Some of the questions we needed to resolve were:
- Boiled down, what is the purpose of the documentation site? It may not be as straight forward as you think.
- What requirements did we have?
- What types of documentation did we currently have?
- How would we present our documentation types in the best way?
- How would content be updated and maintained?
- Who would be in charge of the site?
- What skills did the people who would use our site have?
3. Get a moral buy-in from everyone in your company
Why? Documentation isn’t a one-man job. Producing a useful documentation site that is kept up to date requires a commitment from everyone within the company.
Cups of coffee required: One cup for each employee. Drink it together. Cheers!
Get the company committed to the project
Before getting our hands dirty, our management team made sure that the entire company was dedicated to this project. Documentation would have to figure high on everyone’s list of priorities to get our new site up and running.
When our whole team was on board with the plan, it was easier to free up time in everyone’s schedule for the project. We all knew what we were doing and why. This engagement was more than anything the key to our success.
4. Carefully define your documentation process
Why? Any weaknesses in a process become even more obvious when implementing large changes. So when introducing a new documentation site, avoid obvious showstoppers by thinking before acting.
Cups of coffee required: Loads and loads if you don’t have a well-established process already. If you do: congrats! Save the coffee drinking for the next step!
Define and improve your documentation process
We took the opportunity to go through our existing documentation process. Was it solid? Was everyone happy with the workflow? If not, where and why did problems occur?
Here is an example: One of our main obstacles was the detection and delegation of documentation issues. To solve this, we created a documentation request board in Trello and established a new process for submitting requests.
This is how we put forward documentation issues:
- Everyone within the company submits requests in our Trello board.
- Our documentation specialist reviews the requests. Often we have documentation on the topic that the submitter of the request just hasn’t found, and can provide them with it.
- If the documentation request seems reasonable it is forwarded to the product team’s common inbox. The product team then delegates the documentation requests among themselves.
Having a goalkeeper ensures that invalid documentation requests don’t reach the product team, meaning that they can focus on solving actual problems.
5. Have clear responsibilities
Why? The whole project can get buried in an avalanche of different must-haves and well-meaning suggestions before even getting off the ground unless you have properly defined roles in the project.
Cups of coffee required: Correlates highly with the number of duties within the project.
Define roles and responsibilities
We established responsibilities for the project by answering the following questions.
- Who is in charge of the documentation site, and which aspects of it?
- Who contributes to the documentation?
- Who has the final say when making decisions?
Our sales, marketing, product, and management teams all had different views on how to structure and maintain documentation in the most convenient way. After having the roles sorted out it was easier to evaluate the suggestions and transform the useful ones into action points. Every team could provide their input without halting the project.
6. Set a deadline and milestones
Why? Setting a deadline narrows down the scope and helps streamline the project. It forces you to do a reality check.
Cups of coffee required: As many as you can have in time for the deadline. The amount per day may escalate as the deadline closes in.
Prioritize tasks and narrow down the scope
We set a few milestones on the way towards having our new documentation site up and running. Our long wish list was split into the following categories:
- Must-haves
- Nice-to-haves
- Evaluate-laters
We thought of our documentation as one of our products. What was required for our minimum viable product? What could wait? We went back to our project plan whenever in doubt if a task was essential for the site launch or if it could be looked upon later.
Be willing to re-evaluate your plan
To make sure that we focused on the right things as the project progressed, we adjusted our plan on a regular basis. What priorities did we have? Which tasks absolutely needed to be ready in time for the set deadline? Was this still realistic? The things we would not be able to implement in time were put on a future to-do list.
As the saying goes, “No battle plan ever survives contact with the enemy.”
7. Embrace consistency
Why? Consistency means clarity. Using a well-defined terminology, templates for different documentation types, and having an editor go through all documentation are ways to ensure that the documentation is consistent.
Cups of coffee required: Half a cup. The editor took the rest.
Consistent terminology is your friend
As previously stated, we created a dictionary with commonly used terms. This helped us stick to a consistent terminology when describing our product and its components. This was especially important since we have a complex product.
Use templates for different types of documentation
Consistency is also a matter of the formatting of the documentation. We use templates for different types of documentation: instructions, manuals, and so on. Everyone has access to them. This way our articles follow a logical structure that makes them easy for the user to skim through for certain information.
Have an editor review the documentation
All our newly created documentation is reviewed by our documentation specialist (that would be me) to make sure we not only speak with the same words, but also with the same voice. Having more eyes go through the documentation before it becomes public makes for higher quality documentation and reduces the risk of slipping in any errors.
8. Track your work to follow the progress of the project
Why? Tracking your efforts makes sure that you reach your milestones. And watching the documentation site improve for every ticked-off task is truly rewarding!
Cups of coffee required: Who has time for coffee?! A new documentation site doesn’t create itself. Ok, have some espresso then.
Keep the team members aligned
We use Asana as a collaboration and project planning tool. We love it with with every beat of our hearts!
During this phase, Asana allowed us to keep track of the tiniest details without losing sight of the bigger picture, which was really helpful. What had been done? What was missing? We assigned tasks to each other, set deadlines, and saw how the project progressed. We also had weekly meetings to keep everyone aligned.
9. Collect feedback
Why? Your efforts don’t count if your users are unhappy with what you have created. Be humble and ask for your users’ opinions.
Cups of coffee required: Buy your testers fancy lattes. They deserve it.
Gather feedback from within the company
As our documentation site began to form we started collecting some feedback. Initially we talked to our immediate surroundings. Did they have any suggestions on how to improve what we had created so far?
We also made sure to collect feedback from some unbiased people (a.k.a. people outside our team) to get a couple of fresh eyes on the project. We simply created a feedback-board in Trello where everyone could submit their thoughts on the new documentation site.
The suggestions we collected were folded into the categories used during the initial planning phase:
- Must-haves
- Nice-to-haves
- Evaluate-laters
Let your users speak their mind
We added contact information to suitable people within the company to our documentation site so that our customers could reach out to us directly. We also added voting functionality. A “Was this helpful?” at the end of each article and “Yes/No” buttons requires minimum effort from both us and our site’s visitors. In addition to this, we use Google Analytics to get insights over time about our users’ behaviors and needs without any action required from them.
10. Be prepared to change direction
Why? A documentation site is a work in continuous progress. The input from your co-workers and your users might take you in a new direction. Different times have different needs.
Cups of coffee required: Coffee? By now you might need a drink!
Adapt to the changed priorities
No matter how grand the project, there is always room for improvement. At least if you ask your users.
Both the feedback we collected and the evolution of our product in general pointed us in a slightly new direction than intended, so we had to make changes to our plan whilst in the middle of implementing it. It might seem paradoxical to both stick to a project plan and make changes to it, but by keeping both short-term and long-term goals we could quickly switch priorities without losing sight of the big picture.
Not all action points have to be implemented straight away
Some things can wait, some cannot. By listing the tasks that we would not be able to accomplish this time around we also planned for future improvements. Once again the categories used when prioritizing tasks and collecting feedback helped us evaluate which adjustments were necessary and which could be looked upon later.
Final thoughts
Creating a documentation site is hard work and demanding for everyone involved, but hopefully you will experience the benefits of giving it some love. Not only is it valuable to your users, but you might notice what a moral boost it is for your whole team when things start coming together.
For us, creating a new documentation site has been sort of like a team-building exercise. The attitudes towards creating documentation have definitely changed. Now everyone within the company knows what they are doing when creating documentation and for what purpose they are doing it. We are not done yet, but very happy with what we have accomplished so far.
So, tons and tons of coffee later, here it is: learn.atomia.com