Tips for Documentation at a Tech Start-Up Company
Introduction
Hello there. My name is Aaron Burdick, a manager at a tech company called Zeals in Tokyo, Japan. That information might be not very important for you. However, let me think about who you are? Perhaps you’re someone following Zeals (less likely) or perhaps you’re someone who googled the words “documentation” or “documentation tech” (more likely). So based on that assumption, I’ll also go a bit further and say maybe you’re here because you need help on documentation, that perhaps you’re at a tech company and you feel that your documentation isn’t serving your team. You’re hoping by reading this document that you’ll receive some insights that will guide you to making better docs in your company.
You see, what I’ve done in the first paragraph is a very basic but potentially the most important step in documentation. I’ve imagined my audience. If that was helpful for you, read on. If you thought that was a bit too basic, then perhaps this article isn’t for you.
I’d like to spend the rest of this article, not telling you how to create an entire documentation system from the ground up, but rather some helpful tips that I discovered myself in my quest to improve my tech team’s documentation. I hope that these tips will give you a new perspective on documentation in general, and you’ll have a frame of reference to seek out more complex materials yourself. First, some core stats on my company for a frame of reference.
The Writer’s Context
My Company’s Situation
At Zeals, we have about 80 people in our engineering and product departments combined and including all the other departments in the company greater than 200. About 4 years ago, we were less than 10 people. That’s a lot of people in a fairly short amount of time. It’s also potentially an explosion of documentation. Lack of design and control of the documentation situation did hurt us, but we are doing our best to take care of that situation.
In terms of documentation tooling, we’ve used many different solutions but have settled on a few tools (Miro & Confluence). I’ll do my best to write these opinions mostly agnostic of the tooling itself.
When Zeals decided to overhaul the documentation, we really uprooted a lot of it. It wasn’t any one particular part of the documentation that we wanted to improve, we wanted to improve all of it.
Therefore some disclaimers about this article:
- I won’t assume the size of your team, but ours has a decent number so I hope my suggestions won’t be colored too much by that fact
- I will assume your company uses some sort of documentation tooling but don’t have any strong opinions on what those tools are
- I won’t assume you are reading for any particular kind of documentation advice (e.g. “advice on technical documentation”), but some examples I use may be related to one field or another
OK, let start.
Documentation Tips
First, I’ll give you the list, then I’ll give some details on each point:
- Know your audience
- Create value for your audience
- Get feedback regularly
- Only create what you need and can maintain
- Know your team
- Metadata rocks
Know Your Audience
This is the most important piece of advice I think I can give anyone on this topic. Knowing your audience is not just about writing documentation with that audience in mind, it’s about designing everything about your documentation solution works with that person in mind.
I can’t tell you exactly how to do this. In fact, I think it’s more useful for people to just sit down with their teams and discuss it. The amount of things you can do may be limited by your toolset, but then again thinking about it may cause you to reconsider what tools you use. Here are just a few examples questions that come to mind when one tries to “know their audience”:
- What level technical skill does my audience have?
- How can I answer the audience’s questions in the least amount of words?
- What method of delivery of this documentation would be easiest for this audience?
- What structure or hierarchy of documentation would be easiest for this audience? How can I link my documentation in a sensible and cohesive way for them?
- Does this person even read documentation? Should I consider investing in other forms of media like videos or an active tutorial within my apps?
Create Value for Your Audience
This is mostly just a fancy way of saying the last piece of advice, but it may help to think about how you’re writing docs in this way. Ask yourself, is how we’re doing docs:
- saving my audience time, or is it bogging them down with unnecessary information?
- giving them information that helps them use my product better, or is it delivering outdated or incorrect information?
At the end of the day, if your docs aren’t driving value for the audience, those docs are more likely to become stale, unused, confusing for those actually do read them and overall become a maintenance burden.
Get Feedback Regularly
Two things:
One, it’s hard to say you are creating value without some sort of quantification or measurement. We all think we know what’s important, but in fact without some sort of confirmation, we are just guessing. You can read this blog post or a bunch more just like it on the internet, real actual observation and feedback is the really the only way to understand your audience’s feeling.
And two, as general rule, I think you should be making decisions about your system for documentation about as much as you can receive feedback on it. Of course if you’re just starting out, you’ll have design a system from scratch, so you’ll be making a lot of decisions. However, in general we are not writing documentation for ourselves, but our audience. They are the people that really matter in this equation. If they are telling you it’s broke, then of course you’ll need to fix it, but otherwise you are essentially flying blind.
So how can you get data on this? Well, it really depends on the audience and your tools, but in general this really doesn’t have to be complicated. For example, regarding internal documentation at Zeals, we have a monthly survey which gives us both opinions and metrics from our members which we use to help guide us where we do and don’t need to make changes. The survey asks things like:
‘Technical documentation is easy to find within our team’
How much do you agree or disagree with this statement?
With about 10 minutes of everybody’s time every month, we get invaluable data from the team on where we are strong and weak. I really can’t recommend this step enough.
Know Your Team
It is most likely, not just you who is writing the documentation. Or if you are still a small team, we can think of it a different way: it most likely isn’t you who will maintain and create documentation in the future. Being that there will likely be so many people involved, you have to get organized lest you fall into a bunch of non-standard documents that nobody can seem to find.
There are many different ways of organizing documentation, and a lot of that may depend on your product and how your team is organized. My advice, just pick some general starting point, but make rules, standards and culture around it and your teams. Over time, you may up with something different from how you started out, but at least there will be some method to the madness.
Above, I posted a picture that shows how altexsoft structures its Project Documentation. The important part is that this shows how altexsoft works documentation into their work processes, from planning to release. You may be thinking, “well of course, my team already knows this!” But ask yourself, do they really? Many companies you team have worked at in the past may have had different practices. By making these kinds of rules official, and tying them into actual work processes that people are doing, you are ensuring that everybody’s on the same page and that your products and processes will meet a minimum standard of quality.
The key is not to copy all the documents that other teams produce, but that you are creating rules and structure that suit your team and give you the results that you want. Don’t think about documentation for its own sake, think about what your team really is and what they do, then make a solution around that!
Only Create What You Need and You Can Maintain
Documentation can really weigh your team down with debt, rather than delivering value. If you are constantly writing documents, then when does the product get made? If you’re constantly fighting with outdated documentation, well wouldn’t it have been faster to just read the code in the first place? That’s why I think it’s so important to start with thinking about what you really need and what your team can consistently deliver on.
If you ask 100 team members what documentation you need, you may get 100 different answers. And it’s not to say that all of the suggestions are necessarily bad or not useful, but ask yourself:
- Is it really what your team needs most now and in the future?
- Is this really what my users need?
- Is this an essential document? Or just a nice-to-have?
- What is the level of quality that I’m willing to invest in each one of these documents?
- If we don’t have this document, what will happen?
You have to make decisions about what you will and will not maintain. Sometimes your team may not have a document that covers everything, and that’s OK. Making sacrifices will hopefully give you a balance of the quality and quantity of documentation necessary for your team to get things done.
Metadata Rocks
Metadata really does make your documentation much more versatile, searchable, and reusable. If you tooling allows you to use tags or labels, come up with a strategy to do this for all your docs. Even if a tool you’re using doesn’t give you the above functionality, sometimes there are ways to hack your tools to give you the same effect. Here for example, is a youtube video from K15t on how to “Better Name Your Confluence Pages” to make them more searchable.
At Zeals, we are using tagging standards as a way to ensure that all of our documents are searchable, but also reusable. You see, some of our tools allow us to search by these labels, and we are tagging all of our documentation with the audience it is meant to reach (ex: “audience_dev”, “audience_user”). Therefore, getting all the information relevant to our users for product Foo would be as easy as searching:
- In title: “Foo”
- With tag: “audience_user”
Voila!
Conclusion
If I could go back in time and learn these tips, it would have made all the difference for us as a team. I think in many ways, we learned the hard way, but you don’t have to! Of course you don’t have to follow all these tips, but abiding by even a few will make all the difference. They certainly have for me.
What’s Next?
If you’re not sure where to go from here, I have a few recommendations:
- Check out the above cited materials
- Watch some videos on “technical writing”
