From Data to Wisdom: Why our Technical Writing team focuses on problem-solving
Steph Zalles, Technical Writing Manager, explains what creators of good documentation have in common.
In many developer teams, being the Technical Writer is like being the bassist in a band. There are some very remarkable bassists out there, but mostly you are the person who didn’t get to play guitar.
It’s common to see teams that assign their documentation to the “less busy” member of the team, or to the newer members, so they can learn while they document. Other teams make the most knowledgeable person among them do the documentation, which creates better documentation but is sometimes viewed as punishment, to get the extra work as a consequence of doing a great job.
Throughout my career, I’ve seen many kinds of teams, and many types of Technical Writers. The truth is I haven’t seen one way of working to be necessarily better than the other, but there is one thing all creators of good documentation have in common: They focus on solving problems.
So let’s dig into this concept, shall we?
How we solve problems by making information easier to access
If you google “Knowledge Hierarchy”, you will find the “Knowledge Cycle” multiple times.
Data > Information > Knowledge > Wisdom
Everyone in a knowledge management team knows it by heart, but not everyone has seen data become wisdom in real life, because documentation is often considered a secondary task that needs to be done, and more often than not, few people use it.
The subjectivity of knowledge makes it hard to grasp. I won’t give you a full chapter on theories, but I can tell you what my experience has taught me about each phase in practice. I’ll break it down to explain how these theories can become a practice.
Step one: Data
Nowadays, everything can be considered Data. Even “no data available” is data. So this will depend on what your team has, and what they want to achieve. It will vary every time. Don’t waste too much time looking for databases. If there was enough data to do a Technical Writer’s job, there would be a bot doing that job.
A technical writer’s data is most likely hidden in daily operations. So start by getting some clarity on why your work is necessary for your team. Are they onboarding new people? Are senior developers leaving the team? Is the team struggling with a particular tool?
Identify the problem, and identify what already exists
Often, this means looking at OKRs and SLAs. What is your team trying to achieve, and what’s standing in their way? The person who requests a document will not always give you this. It’s not their job. A Technical Writer completes the task. A knowledge professional’s job is finding the way in which the task contributes to the team’s goals. Even before getting the information for a document, identify how this document can make their work better.
Step two: Information
This is usually the request Technical Writers get: “I want this information documented”. The truth is, Information is Data rearranged and analyzed to have a meaning. To give meaning to the information, you need to understand who is going to read this document and give them context. What do they already know? What do they ignore? When and why will they need to know this?
This is why many teams use language professionals as their technical writers, more than developers. If this is your case, get technical. Learn code basics, and understand what your engineers need. If you’re a developer, get into UX. Understanding the audience is key to making your information valuable for them.
The information a Technical Writer is given is not to be copied and pasted. It is to be analyzed and restructured for the people who will read the document. Sometimes this means turning one document into four or merging six documents into one. This is why a robot can’t do a technical writer’s job. The source of the information is never the user. Identify the audience of your documentation.
Documentation must be designed so that the people who read it understand what the people who need you to create it want. By this time, you should be well aware of the problem you are trying to solve. It’s like getting your final test the night before. Study the information with that mindset. Solve the test as you read the information you get.
Step three: Knowledge
Now the hard part begins. The biggest difference between information and knowledge is that knowledge solves problems. Often. It’s common to ask why the team is not following, or even reading the documentation. If this happens in your team, read your document thinking “What’s in it for them?”. “They save time” is a common answer. If your document saves 5 minutes in reading but requires six searches to find, then it’s not working. They don’t have to make it easy for you. It’s your document that should make it easier for them. It’s part of your job to make sure they have it handy on a few clicks when necessary.
Whether documentation was made by an engineer on the team or a Technical Writer, the document will be better if it was designed for the user of the information to save time, reduce cost, or in general, add value to their work. Documentation should be related to the main issues faced daily by the people using this information.
It should not get in the way of their objectives. Forcing engineers to read documents, or comment on them is a terrible practice. Voluntary use is your best feedback. They have to WANT to use your document because it makes their job faster, easier, and better.
If the document is about coding standards to follow, it should be easy to read, handy, and highlight the most commonly used and relevant guidelines, and have a quick cheat sheet on the ones that are less common, and easily overlooked or forgotten. We should never force people to use the knowledge we create. Knowledge use is feedback. If your documents are not being used, or not being found, then they’re not solving problems. Title them well, tag them appropriately, and make sure they have relevant information that is easy to scan, without having to read 3 paragraphs before you reach a solution.
Step four: Wisdom
This is the final stage of maturity. It means the use of the knowledge created is helping create better knowledge. It means you solve bigger problems. This is when your work is adding value that is appreciated and enriched by the documentation owners and users.
Wisdom is what you get when other teams trust you with their information because you offer solutions that adapt to their needs.
So how do we get there as a team?
When I joined Wildlife, I got to meet their small Technical Writing team. I heard the word around was that the engineers were not valuing the work of the Technical Writers very highly, and they wanted to change that.
They helped me explore the Wiki (the company go-to source of information), and I have to say that, even though some documents were very good, they were also very hard to find.
Being used to work for very big companies, with multiple clients, and support teams, I was used to seeing messy knowledge bases. This was not one of the worst I’d seen. It could use some organizing, but in general, this wiki contained good information and well-defined spaces.
There was a lot of useful information, but it was mostly hard to find (sometimes even for people within that team) and even worse, easy to confuse with outdated information. There also was little use of tags and naming conventions, and I couldn’t find one template that was practical for general use.
Each one of the Technical Writers — in their own way — were trying to bring a little extra to the teams they were working with, and I thought maybe, they just needed the right guidance to get there.
Knowing this, I wanted that “extra” effort to be focused on what adds value for the engineers. I began working with each one of them on templates and standardized structures, so what is working for one team or squad can be useful for all Wilders.
When an engineer adds a new document, I want it to be as easy as clicking a button that creates a “fill in the blanks” document that they pour their knowledge into. When they make a search, I want the right document to appear, and the title of such document to be very clear on its content.
We have a long way to go, but I see a future where every team can get more than a document when they make a request from our team, I want every team to get guidelines, standards, and structures that are functional, scalable, findable, and in general, a tool to grow without worrying about the mess.
We want to empower every team to think big, move fast, and stay committed to the work they’re best at. We’ll do what we are best at, so that when you get there, your wiki is waiting for you, clean, organized, and ready for your next challenge.
