How to "tear down" your documentation and start living
Today we will talk about how to get rid of documentation that does not work, describes some kind of legacy, is not organized, does not match the identity of your brand, but there it’s just bad documentation. In order to prepare and reorganize good, valid, logically organized and relevant documentation of the brand identity. And as soon as you can get rid of the documentation - everything will be rosy and beautiful.
Under the cut, the translation of the report by Alexandra White, a technical writer from Google, at the Write the Docs Prague 2018 conference. And a week later, on April 26, 2019, Alexander will speak at our KnowledgeConf conference on “How to create compelling multimedia documentation” . Alexandra will tell how to embed multimedia formats (video, audio, gif) in the process of creating artifacts and knowledge packaging, when multimedia formats are best suited, and when they will not work, how to measure the effectiveness of multimedia artifacts and overcome their limitations.
For a start I will tell you about myself, what I am from. My name is Alexandra White, I live in New York, I am a technical writer, and before that I worked as a web developer in a television company. There, people worked for 5, 10, 15 years surrounded by a large amount of legacy information about where the code lies and how it works.
')
It was very difficult to get to work, find any information, had to endlessly ask questions to engineers. It took a lot of time, so I began to promote comments in the code, writing actual readme, and later it became my work in the cloud company Joyent.
When I came to Joyent, I knew very little about cloud storage: I heard the main popular terms, I was at one conference. It would be strange to tell people how to use our products when I have no idea about this. So I needed to “run twice as fast.” For the next eight months, I was the only technical writer and editor in the project; before, these tasks were performed by engineers, a technical support team, and product managers. They did the most dependent on them, but within their priorities.
Frankly, when I came to the project, chaos reigned there, thousands of documents, not organized, not read. I tried to work as quickly as possible to close the spaces. For example, we did not have introductory documentation, how to start working with containers in order to start working with a product, this was my first challenge. I started working on Docker introductory instructions for our main product, Triton.
Finally, when I managed to get rid of this urgent task, and, as it seems to me, I began to understand the product, I took up my favorite thing - I began to “demolish” the old documentation.
Today I will tell you how to do it, how to destroy the old and build a new one, what it cost, how I created the content strategy and stylgide, and, as a bonus, tell you what to do if circumstances are not on your side and obstacles in work appear .
And I will also share what I did not take into account when I started working on the project, so that when you plan your work, you can immediately do everything right.
In August 2016, starting work on the project, I conducted an audit of the content and was horrified, we had 9 (!) Different documentation sites . I didn’t even know about most of them during the year of work. And there was not a single description of how to write documentation, so you needed or a lot of effort when searching for information, or to know very sophisticated ways of operating each of these sites.
In addition, I discovered a huge technical debt, which arose from the fact that someone published a document and forgot about it, "leaving to die."
For a start, I will show how many different sites with documentation I was able to detect. When I find it difficult to find the right documentation, I use Google search. So I crossed my fingers and hoped that the information found would be correct. It was not the best solution, because many of our sites are closed by authorization.
Why, even our engineers use Google to find the right product information. Therein lies the problem.
So, the first repository is the wiki , it is maintained by system operators and the support team. Of all the documentation, this is the most relevant, but it is closed by authorization, and the search for information in it was the secret of the support team, which they did not want to share.
Another repository is the JIRA ticket tracker .
Various bug reports were stored there, engineers and members of the support team described how to fix these bugs, how to solve a particular issue, but the information remained on these tickets, never getting into the public documentation.
We also had a website with API documentation , made using a single source technology from the source code. It's cool, that's exactly what I'm aiming for - the documentation is as close to the code as possible.
However, in fact, the code was updated faster than the documentation corresponding to it.
Finally, we had a product blog . You will probably say that a blog is marketing, but no, it contained very deep technical documents, descriptions of integrations and conceptual reviews, many of which were much better than our documentation. By the way, here she is.
It is assumed that this is the main place where users can get support and understand how our cloud storage works. But, unfortunately, this documentation was supported by the product team, not the engineers. Some of our engineers were completely unaware of the existence of this website. And, again, this is public documentation.
So, we are terrified. There is no documentation life cycle. The document is published - great, you no longer need to think about it, everything is fine. This is the problem. The content was created by a variety of different, not similar voices: technical support, engineers, product managers, and not one Joyent voice. Each stakeholder has his own opinion, his own vision of how the document should look and where it should be placed.
In addition, no one has tested this website to understand how users read it, what they are looking for, to better understand what they need.
Our job as technical writers is to help users find answers to their questions, be it to solve a problem in a moment of panic or to find some trifle that will help you use the product more effectively. And our job is to help colleagues write better. We cannot be experts in everything. We rely on subject matter experts - experts in a particular area so that we can help users know what they NEED to know.
Technical writers are shepherds . We lead users and colleagues to answers and practical solutions. And sometimes the best solution is to start from the beginning. But after so many investments in the existing infrastructure, burning everything to the bottom seems risky for stakeholders.
It is important to understand what good arguments are and how important they are. I understood it in childhood.
My brother and I really wanted a dog, but it seemed to dad that it was a heavy burden. So how can I convince my father that a dog is a useful and necessary member of the family, and not just an animal that requires investment of money and strength.
We wrote a detailed explanation of how the appearance of the dog will make our family happier and how we plan to share the duties of feeding, walking and cleaning after it. We offered a schedule and even figured out how to make money for the services of a veterinarian. As you can see, the arguments worked. We got Maggie, the wonderful pug, she became a member of the family.
After all, if you cannot convince the leadership of this, you may not need the changes. A good argument is to write a draft of future changes.
When you write a project, remember that you are not your audience. This is a marketing document that says: “This job is important, and here's why. This is how I plan to correct our problems, and this will bring such a profit to the company. ”
The very process of writing a project to restructure the documentation will help you better understand the task from a practical point of view, understand the problems you have encountered, whether it is lack of content, unorganized documents, outdated information or something else.
As I said, we had a number of problems with the documentation in Joyent. But just because I knew that the documentation is out of shape does not mean that I could ignore the urgent needs of clients. I could not afford the luxury of stopping responding to tickets while I was making plans, so I also had to write new and improve old documents. I did not have the opportunity to stop.
However, working on the project to convince the management helped me then correct the strategic problems with the documentation so that in the future there were fewer of them.
Let's look at my project, which helped me get a “Yes” answer to the proposal to “pull down” the documentation.
First of all, every successful project begins with an introduction. You rightly ask why this is important? If people don’t even master the first page, if you don’t convince them from the first lines, then it doesn’t matter how steep the arguments are. First you need to convey to them why this is a problem, why it exists. Prepare the reader for what he should expect on the following pages.
In the first version of the project, I pointed out the fact that Joyent had a long technical debt, it was high time to redo the documentation, and now we are reaping the benefits of this. This was to be expected with 9 different documentation sites.
To reinforce the arguments, I began to talk about the company's goals, for example, to become number one on the cloud providers market, rather than a niche company for geeks. But just to write “we are the best” in marketing materials is not enough to achieve this goal, you need to tell the market how to use our product. If no one knows, then no matter how cool the product you make.
Think about your company's goals. How you improve the documentation will affect the company's profits.
To begin, I conducted a content audit. I listed all our documentation stores: what is stored in them, what CMS is used, who is the main audience of each of the sites, who writes the documents. Then I recommended which sites should be left, from which to transfer information, and which - to be completely demolished.
The number one priority for a technical writer is the audience. Everything we do - we do for other people, not for ourselves. If you are lucky to have a grocery or marketing team that segment an audience for you, hold on to it, I did not have such a team.
I myself divided the audience into four groups according to goals:
Dividing the audience into these groups, I began to better understand their goals in order to create content that meets expectations.
Our priority problem was the diversity of websites, so the number one goal is to consolidate the content , it was necessary to reorganize it. And this means, first of all, to understand what is “good” and what is “bad”, what is worth saving, and what is not.
The second goal is to set up coherent templates for different types of content , for example, step-by-step instructions, FAQ, overview, so that the reader clearly understands what kind of document he is reading. This helped us make the content more findable.
In addition, we needed internal goals , for example, to improve the process of how we write understandable and informative documents from request to publication. We wrote a guideline for compiling a request for a document, in it we prescribed mandatory questions that need to be answered, for example, why this document or what information should be included in it. Thus, I managed to avoid a situation where I ask questions like: “What else is a new feature? What do you mean you urgently need documentation on it, tell me more. ”
Finally, a documentation plan would not be complete without a plan for decommissioning documents: What if the document is outdated or describes a product or function that no longer exists? How do we plan to archive such materials? Maybe you should delete them completely?
That's what a “document life cycle plan” is, you have to think through every step from creation to deletion of a document. For Joyent, this meant that from the moment an idea appeared, before writing the text, then from publishing it to updating, archiving or deleting. Each step is recorded, there are checks that the content is not lost forever, that warnings and redirects are configured from the old document to the new one. If the user searches for an old document, he should not see 404.
As a result, we have a very long list of tasks. We had to re-describe what is included in the product scopes, what should be the site architecture, what types of content, what the site should look like up to the design.
Here are a few items that I will not disclose in detail: this is the schedule, the roadmap, the tools needed for implementation, the time and cost estimates for reworking documents and the purchase of tools, as well as a number of additional questions, such as whether we want open source documentation? If yes, how do we plan to implement it?
Regardless of whether you end up with a project - long and detailed or small and compact, for example, “Alexander and Philip want a dog, because ...”, it is important that your project reflects clear and understandable reasons why you are planning do so and not otherwise, how do you plan to solve the problem and how long will it take.
So, your project is ready, you have impressed the manager, he has allocated resources and time, and then what? Planning is great, the project helps you identify those products that need attention. You can reuse part of the project, many of my projects have become templates for future work.
The time has come to put all the pieces together. The next step after creating and approving a project is content strategy. In fact, you have already done most of the work.
Six years ago, I worked as a digital marketing manager for a non-profit organization. Of course, marketing and technical content vary, the purpose of marketing is to sell, and technical content to help, teach, or assist in accomplishing a task. However, we can use the techniques of marketing. Content strategy allows to achieve consistency in branding. When a user uses products, reads promotional materials, reads documentation, he should feel the unity of the brand.
For example, this is how the sidebar looked on docs.joyent.com before. Frankly, the services were renamed several times before I joined the company, but it was important to make sure that our public product, the Triton Compute Service, was updated uniformly.
On the left you see the Joyent Cloud product menu items. This is the “legacy” of the previous product naming - Joyent Public Cloud. I updated them, calling the section Triton images, now it corresponds to the product name.
We still have a problem with the company name. We constantly argue with the boss, but more often I lose. Users call the product JPC, in addition, this acronym is used in the code. It is difficult to leave this name in the past. But for our part, we can adhere to the name of the product in the materials.
It can be part of a stylgide to standardize how we talk about ourselves, how we talk about other brands, such as Docker. A stylegide can help agree on what tone, what grammatical structures, text styles and rules we use. As a result, you yourself will write better and get better quality drafts from your colleagues.
Another important part of the strategy is to “demolish” outdated documents and materials. I wrote messages to various teams that their content has not been updated for more than two years and will be deleted.
But, in fact, I did not delete it completely, I simply removed it from public access and sent it to the archive until I was convinced that nothing valuable was left there.
Interesting fact: Joyent is a subsidiary of Samsung, which means our main decision makers are in Korea.
After two years of working on the documentation in Joyent, I was asked to start a completely new project. It meant to freeze the content strategy that I carefully built, based on the knowledge of the product. Soon I stopped working on pull requests, which I received for a new, user-oriented version of the site with documentation.
At this point, almost all sites that we thought were outdated were still online. But I learned from my work and started a new project from scratch.
You should not feel a personal connection with what you are doing, otherwise it will be difficult for you to give up everything that you have done. Nothing should be so valuable to you. Memorize lessons learned and use in future projects.
Despite the fact that I had to leave everything behind, I still learned a few lessons from my work. That is exactly what I missed.
The first lesson is user testing . In fact, this should have been made number one priority, along with the budget for the tools and time to spend talking to users about what they like in the documentation and what they don’t.
Moreover, I would like to more closely communicate with colleagues about the same thing. After all, they are also users of documentation, their voice is important. If you include them in the process, they will have more motivation to help with the documentation.
I know that user testing is very important, even in the format of a regular survey, you can find out the feelings of people that they would like to see. I should push this task.
Equally important is the idea of empathy for the engineering team . How do you facilitate colleagues to write better content, while you can focus on more general strategy and supporting content?
There are several ways to embed colleagues in the process of creating documentation, how to sell them, why this is important. If we want them to stop googling answers, create those answers within the company.
Also, remember that even those colleagues who believe in the importance of documentation have their own priorities. They are busy people. They have their own goals and objectives before the leadership. They need to finish their work first and then help you. Be kind, support them.
Probably the hardest part of this process is to make sure that experts and engineers understand that this process is important. Even better, the documentation is part of your company's engineering culture .
Documentation is the task of everyone, not just writers. If everyone wants to solve user problems, the product becomes better.
Taking diversity into account is an important moment for Joyent, because we have employees in South Korea, we needed to understand how they think. Their way of finding information and solving problems was often different from ours.
The culture of the organization affects the documentation. In fact, writing texts always depends on how we learn, and on how we think others should learn.
Diversity is important. Having a team of people with different backgrounds allows you to better take into account different learning models and create better content. And there is plenty of room for growth.
I recall the main ideas of this story. Firstly, how to write a cool project for processing documentation, secondly, how to take the first steps to implement this project, and, finally, about what I initially missed in the process, but you shouldn’t. Key findings include:
Be the shepherd of your flock. Lead users and colleagues to the answers they need.
Useful materials for the report:
Under the cut, the translation of the report by Alexandra White, a technical writer from Google, at the Write the Docs Prague 2018 conference. And a week later, on April 26, 2019, Alexander will speak at our KnowledgeConf conference on “How to create compelling multimedia documentation” . Alexandra will tell how to embed multimedia formats (video, audio, gif) in the process of creating artifacts and knowledge packaging, when multimedia formats are best suited, and when they will not work, how to measure the effectiveness of multimedia artifacts and overcome their limitations.
For a start I will tell you about myself, what I am from. My name is Alexandra White, I live in New York, I am a technical writer, and before that I worked as a web developer in a television company. There, people worked for 5, 10, 15 years surrounded by a large amount of legacy information about where the code lies and how it works.
')
It was very difficult to get to work, find any information, had to endlessly ask questions to engineers. It took a lot of time, so I began to promote comments in the code, writing actual readme, and later it became my work in the cloud company Joyent.
When I came to Joyent, I knew very little about cloud storage: I heard the main popular terms, I was at one conference. It would be strange to tell people how to use our products when I have no idea about this. So I needed to “run twice as fast.” For the next eight months, I was the only technical writer and editor in the project; before, these tasks were performed by engineers, a technical support team, and product managers. They did the most dependent on them, but within their priorities.
Frankly, when I came to the project, chaos reigned there, thousands of documents, not organized, not read. I tried to work as quickly as possible to close the spaces. For example, we did not have introductory documentation, how to start working with containers in order to start working with a product, this was my first challenge. I started working on Docker introductory instructions for our main product, Triton.
Finally, when I managed to get rid of this urgent task, and, as it seems to me, I began to understand the product, I took up my favorite thing - I began to “demolish” the old documentation.
Today I will tell you how to do it, how to destroy the old and build a new one, what it cost, how I created the content strategy and stylgide, and, as a bonus, tell you what to do if circumstances are not on your side and obstacles in work appear .
And I will also share what I did not take into account when I started working on the project, so that when you plan your work, you can immediately do everything right.
In August 2016, starting work on the project, I conducted an audit of the content and was horrified, we had 9 (!) Different documentation sites . I didn’t even know about most of them during the year of work. And there was not a single description of how to write documentation, so you needed or a lot of effort when searching for information, or to know very sophisticated ways of operating each of these sites.
In addition, I discovered a huge technical debt, which arose from the fact that someone published a document and forgot about it, "leaving to die."
For a start, I will show how many different sites with documentation I was able to detect. When I find it difficult to find the right documentation, I use Google search. So I crossed my fingers and hoped that the information found would be correct. It was not the best solution, because many of our sites are closed by authorization.
Why, even our engineers use Google to find the right product information. Therein lies the problem.
So, the first repository is the wiki , it is maintained by system operators and the support team. Of all the documentation, this is the most relevant, but it is closed by authorization, and the search for information in it was the secret of the support team, which they did not want to share.
Another repository is the JIRA ticket tracker .
Various bug reports were stored there, engineers and members of the support team described how to fix these bugs, how to solve a particular issue, but the information remained on these tickets, never getting into the public documentation.
We also had a website with API documentation , made using a single source technology from the source code. It's cool, that's exactly what I'm aiming for - the documentation is as close to the code as possible.
However, in fact, the code was updated faster than the documentation corresponding to it.
Finally, we had a product blog . You will probably say that a blog is marketing, but no, it contained very deep technical documents, descriptions of integrations and conceptual reviews, many of which were much better than our documentation. By the way, here she is.
It is assumed that this is the main place where users can get support and understand how our cloud storage works. But, unfortunately, this documentation was supported by the product team, not the engineers. Some of our engineers were completely unaware of the existence of this website. And, again, this is public documentation.
So, we are terrified. There is no documentation life cycle. The document is published - great, you no longer need to think about it, everything is fine. This is the problem. The content was created by a variety of different, not similar voices: technical support, engineers, product managers, and not one Joyent voice. Each stakeholder has his own opinion, his own vision of how the document should look and where it should be placed.
In addition, no one has tested this website to understand how users read it, what they are looking for, to better understand what they need.
But any chaos can be corrected, there are at least two ways: put in order or start from the beginning.
Our job as technical writers is to help users find answers to their questions, be it to solve a problem in a moment of panic or to find some trifle that will help you use the product more effectively. And our job is to help colleagues write better. We cannot be experts in everything. We rely on subject matter experts - experts in a particular area so that we can help users know what they NEED to know.
Technical writers are shepherds . We lead users and colleagues to answers and practical solutions. And sometimes the best solution is to start from the beginning. But after so many investments in the existing infrastructure, burning everything to the bottom seems risky for stakeholders.
It is important to understand what good arguments are and how important they are. I understood it in childhood.
My brother and I really wanted a dog, but it seemed to dad that it was a heavy burden. So how can I convince my father that a dog is a useful and necessary member of the family, and not just an animal that requires investment of money and strength.
We wrote a detailed explanation of how the appearance of the dog will make our family happier and how we plan to share the duties of feeding, walking and cleaning after it. We offered a schedule and even figured out how to make money for the services of a veterinarian. As you can see, the arguments worked. We got Maggie, the wonderful pug, she became a member of the family.
To come up with arguments for the leadership that the work on the "demolition" of the documentation deserves the waste of time and money, this is half the way to good documentation.
After all, if you cannot convince the leadership of this, you may not need the changes. A good argument is to write a draft of future changes.
We write the project for the head
When you write a project, remember that you are not your audience. This is a marketing document that says: “This job is important, and here's why. This is how I plan to correct our problems, and this will bring such a profit to the company. ”
The very process of writing a project to restructure the documentation will help you better understand the task from a practical point of view, understand the problems you have encountered, whether it is lack of content, unorganized documents, outdated information or something else.
As I said, we had a number of problems with the documentation in Joyent. But just because I knew that the documentation is out of shape does not mean that I could ignore the urgent needs of clients. I could not afford the luxury of stopping responding to tickets while I was making plans, so I also had to write new and improve old documents. I did not have the opportunity to stop.
However, working on the project to convince the management helped me then correct the strategic problems with the documentation so that in the future there were fewer of them.
If you cannot convince the manager that changes are needed, then you can hardly change anything in the documentation.
Let's look at my project, which helped me get a “Yes” answer to the proposal to “pull down” the documentation.
First of all, every successful project begins with an introduction. You rightly ask why this is important? If people don’t even master the first page, if you don’t convince them from the first lines, then it doesn’t matter how steep the arguments are. First you need to convey to them why this is a problem, why it exists. Prepare the reader for what he should expect on the following pages.
In the first version of the project, I pointed out the fact that Joyent had a long technical debt, it was high time to redo the documentation, and now we are reaping the benefits of this. This was to be expected with 9 different documentation sites.
To reinforce the arguments, I began to talk about the company's goals, for example, to become number one on the cloud providers market, rather than a niche company for geeks. But just to write “we are the best” in marketing materials is not enough to achieve this goal, you need to tell the market how to use our product. If no one knows, then no matter how cool the product you make.
Think about your company's goals. How you improve the documentation will affect the company's profits.
To begin, I conducted a content audit. I listed all our documentation stores: what is stored in them, what CMS is used, who is the main audience of each of the sites, who writes the documents. Then I recommended which sites should be left, from which to transfer information, and which - to be completely demolished.
The number one priority for a technical writer is the audience. Everything we do - we do for other people, not for ourselves. If you are lucky to have a grocery or marketing team that segment an audience for you, hold on to it, I did not have such a team.
I myself divided the audience into four groups according to goals:
- First of all, these are business owners , people who are interested in purchasing a product, they want to understand that he knows how, the general principles of work, how to start working with him.
- The second category is researchers , they are already familiar with the product, but want to learn about advanced features.
- Third, these are people who want to solve a problem , they came to the documentation in a panic, they have a problem, and they want to solve it quickly.
- Finally, the fourth category is detectives , it can be product managers or engineers who are interested in whether your product can perform some specific function.
Dividing the audience into these groups, I began to better understand their goals in order to create content that meets expectations.
Our priority problem was the diversity of websites, so the number one goal is to consolidate the content , it was necessary to reorganize it. And this means, first of all, to understand what is “good” and what is “bad”, what is worth saving, and what is not.
The second goal is to set up coherent templates for different types of content , for example, step-by-step instructions, FAQ, overview, so that the reader clearly understands what kind of document he is reading. This helped us make the content more findable.
In addition, we needed internal goals , for example, to improve the process of how we write understandable and informative documents from request to publication. We wrote a guideline for compiling a request for a document, in it we prescribed mandatory questions that need to be answered, for example, why this document or what information should be included in it. Thus, I managed to avoid a situation where I ask questions like: “What else is a new feature? What do you mean you urgently need documentation on it, tell me more. ”
Finally, a documentation plan would not be complete without a plan for decommissioning documents: What if the document is outdated or describes a product or function that no longer exists? How do we plan to archive such materials? Maybe you should delete them completely?
That's what a “document life cycle plan” is, you have to think through every step from creation to deletion of a document. For Joyent, this meant that from the moment an idea appeared, before writing the text, then from publishing it to updating, archiving or deleting. Each step is recorded, there are checks that the content is not lost forever, that warnings and redirects are configured from the old document to the new one. If the user searches for an old document, he should not see 404.
As a result, we have a very long list of tasks. We had to re-describe what is included in the product scopes, what should be the site architecture, what types of content, what the site should look like up to the design.
Here are a few items that I will not disclose in detail: this is the schedule, the roadmap, the tools needed for implementation, the time and cost estimates for reworking documents and the purchase of tools, as well as a number of additional questions, such as whether we want open source documentation? If yes, how do we plan to implement it?
Regardless of whether you end up with a project - long and detailed or small and compact, for example, “Alexander and Philip want a dog, because ...”, it is important that your project reflects clear and understandable reasons why you are planning do so and not otherwise, how do you plan to solve the problem and how long will it take.
We realize the project
So, your project is ready, you have impressed the manager, he has allocated resources and time, and then what? Planning is great, the project helps you identify those products that need attention. You can reuse part of the project, many of my projects have become templates for future work.
The time has come to put all the pieces together. The next step after creating and approving a project is content strategy. In fact, you have already done most of the work.
Six years ago, I worked as a digital marketing manager for a non-profit organization. Of course, marketing and technical content vary, the purpose of marketing is to sell, and technical content to help, teach, or assist in accomplishing a task. However, we can use the techniques of marketing. Content strategy allows to achieve consistency in branding. When a user uses products, reads promotional materials, reads documentation, he should feel the unity of the brand.
For example, this is how the sidebar looked on docs.joyent.com before. Frankly, the services were renamed several times before I joined the company, but it was important to make sure that our public product, the Triton Compute Service, was updated uniformly.
On the left you see the Joyent Cloud product menu items. This is the “legacy” of the previous product naming - Joyent Public Cloud. I updated them, calling the section Triton images, now it corresponds to the product name.
We still have a problem with the company name. We constantly argue with the boss, but more often I lose. Users call the product JPC, in addition, this acronym is used in the code. It is difficult to leave this name in the past. But for our part, we can adhere to the name of the product in the materials.
Speaking about naming products, it is important to clearly describe the rules of how we call products and components, create an updated glossary to achieve consistency.
It can be part of a stylgide to standardize how we talk about ourselves, how we talk about other brands, such as Docker. A stylegide can help agree on what tone, what grammatical structures, text styles and rules we use. As a result, you yourself will write better and get better quality drafts from your colleagues.
Another important part of the strategy is to “demolish” outdated documents and materials. I wrote messages to various teams that their content has not been updated for more than two years and will be deleted.
But, in fact, I did not delete it completely, I simply removed it from public access and sent it to the archive until I was convinced that nothing valuable was left there.
Interesting fact: Joyent is a subsidiary of Samsung, which means our main decision makers are in Korea.
After two years of working on the documentation in Joyent, I was asked to start a completely new project. It meant to freeze the content strategy that I carefully built, based on the knowledge of the product. Soon I stopped working on pull requests, which I received for a new, user-oriented version of the site with documentation.
At this point, almost all sites that we thought were outdated were still online. But I learned from my work and started a new project from scratch.
The conclusion is: sometimes you have to throw all the work into the pipe due to the circumstances.
You should not feel a personal connection with what you are doing, otherwise it will be difficult for you to give up everything that you have done. Nothing should be so valuable to you. Memorize lessons learned and use in future projects.
What have we missed
Despite the fact that I had to leave everything behind, I still learned a few lessons from my work. That is exactly what I missed.
The first lesson is user testing . In fact, this should have been made number one priority, along with the budget for the tools and time to spend talking to users about what they like in the documentation and what they don’t.
Moreover, I would like to more closely communicate with colleagues about the same thing. After all, they are also users of documentation, their voice is important. If you include them in the process, they will have more motivation to help with the documentation.
I know that user testing is very important, even in the format of a regular survey, you can find out the feelings of people that they would like to see. I should push this task.
Equally important is the idea of empathy for the engineering team . How do you facilitate colleagues to write better content, while you can focus on more general strategy and supporting content?
There are several ways to embed colleagues in the process of creating documentation, how to sell them, why this is important. If we want them to stop googling answers, create those answers within the company.
Also, remember that even those colleagues who believe in the importance of documentation have their own priorities. They are busy people. They have their own goals and objectives before the leadership. They need to finish their work first and then help you. Be kind, support them.
Probably the hardest part of this process is to make sure that experts and engineers understand that this process is important. Even better, the documentation is part of your company's engineering culture .
Documentation is the task of everyone, not just writers. If everyone wants to solve user problems, the product becomes better.
Taking diversity into account is an important moment for Joyent, because we have employees in South Korea, we needed to understand how they think. Their way of finding information and solving problems was often different from ours.
The culture of the organization affects the documentation. In fact, writing texts always depends on how we learn, and on how we think others should learn.
Diversity is important. Having a team of people with different backgrounds allows you to better take into account different learning models and create better content. And there is plenty of room for growth.
I recall the main ideas of this story. Firstly, how to write a cool project for processing documentation, secondly, how to take the first steps to implement this project, and, finally, about what I initially missed in the process, but you shouldn’t. Key findings include:
- Plans are the key to success. They include project and strategy.
- But sometimes plans mean nothing due to the intervention of circumstances. Sometimes the result immediately goes into production, and sometimes you have to leave it and move on, start all over again after you have done half the work.
- Documentation is important for both users and engineers. You have critical skills, you help others understand complex concepts and processes. Your work is as important as you are. Even if you do not say that.
Be the shepherd of your flock. Lead users and colleagues to the answers they need.
Useful materials for the report:
You can subscribe to Alexandra on Twitter , Github , read her personal blog or chat with her live on April 26 on the KnowledgeConf 2019 after her report or on the stand of the international technical writers community Write the docs.
Source: https://habr.com/ru/post/447782/
All Articles