How to "tear down" your documentation and start living

    Today we’ll talk about how to get rid of documentation that doesn’t work, describes some kind of legacy, is not organized, does not correspond to the identity of your brand, but what is there - just bad documentation. To then prepare and reorganize good, valid, logically organized and brand identity documentation. And as soon as you can get rid of the documentation - everything will become rosy and beautiful.



    Under the cut, a translation of the report by Alexandra White, technical writer from Google, at the Write the Docs Prague 2018 conference. And after a week on April 26, 2019, Alexandra will speak at our KnowledgeConf conference with a report “How to create compelling multimedia documentation”. Alexandra will tell you how to embed multimedia formats (video, audio, gif) in the process of creating artifacts and packaging knowledge, when multimedia formats will work best and when they won’t work, how to measure the effectiveness of multimedia artifacts and overcome their limitations.

    To begin, I’ll tell you about myself, what and how I know. 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 started, find any information, had to endlessly ask engineers questions. It took a lot of time, so I started to promote comments in the code, writing relevant readme, and later it became my job at the cloud-based company Joyent.

    When I came to Joyent, I knew little about cloud storage: I heard the main popular terms, was at a conference. It would be strange to tell people how to use our products when I have no idea about it. Therefore, I needed to "run twice as fast." Over 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 their best, but within the framework of their priorities.

    To admit, 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 gaps. For example, we did not have introductory documentation on how to start working with containers in order to start working with a product, this was my first call. I started working on Docker introductory instructions for our main product, Triton.

    Finally, when I managed to get rid of this urgent task, and, it seems to me, I began to understand the product, I took up my favorite business - 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 a content strategy and style guide, and, as a bonus, I will tell you what to do if circumstances are not on your side and there are obstacles to work .

    I’ll also share that I didn’t take into account when I started working on the project, so that when you plan the work, you can immediately do everything right.

    In August 2016, starting work on the project, I conducted a content audit and was terrified, we had 9 (!) Different sites with documentation. I did not 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 either a huge effort to find information, or to know the very sophisticated ways of working each of these sites.

    In addition, I discovered a huge technical debt that arose because someone published a document and forgot about it, “leaving it to die.”

    To begin with, I will show how many different sites with documentation I managed to find. When it’s hard for me to find the right documentation, I use Google search. So I crossed my fingers and hoped that the information found would be correct. This was not the best solution, because many of our sites are closed by authorization.



    Yes there, even our engineers use Google to find the right product information. This is the problem.

    So, the first repository is a wiki , it is maintained by system operators and a 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 in these tickets, never falling into public documentation.

    We also had a website with documentationAPI made using a single source technology from source code. It's cool, that's exactly what I am 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 published 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.



    This is supposedly the primary 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 not even aware 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 - excellent, you no longer need to think about it, everything is in order. This is the problem. The content was created by many different, different voices: tech support, engineers, product managers, and not just 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, in order to better understand what exactly they need.

    But any chaos can be fixed, there are at least two ways: to put in order or start from the beginning.

    Our work as technical writers is to help users find answers to their questions, whether they solve the problem in a moment of panic or find some little thing that will help to use the product more efficiently. And our job is to help colleagues write better. We cannot be experts in everything. We rely on subject matter experts - experts in a specific 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 ground seems risky for stakeholders.

    It is important to understand what good arguments are and how important they are. I understood this as a child.



    My brother and I really wanted a dog, but it seemed to dad that this 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 effort.

    We wrote a detailed justification of how a dog’s appearance will make our family happier and how we plan to share responsibilities for feeding, walking and cleaning after her. We proposed a schedule and even figured out how we plan to make money for the services of a veterinarian. As you can see, the arguments worked. We got a wonderful pug, Maggie, she became a member of the family.

    To come up with arguments for the leadership that work on the “demolition” of documentation deserves a waste of time and money, this is already half the way to good documentation.

    After all, if you cannot convince management of this, you may not need the change. A good argument is to write a draft of future changes.

    We are writing a project for the leader


    When you write a project, remember that you are not your audience. This is a marketing document that says: “This work is important, and that's why. This is how I plan to fix our problems, and this will bring such a profit to the company. ”

    The process of writing a documentation restructuring project itself will help you better understand the problem from a practical point of view, to understand the problems that you have encountered, whether it is a 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 was not in shape does not mean that I could ignore the urgent needs of clients. I could not afford the luxury of stopping answering tickets while I was making plans, so I also had to write new ones and improve old documents. I did not have the opportunity to stop.

    However, working on the project to convince the management, then helped me fix strategic problems with the documentation so that in the future there would be less.

    If you cannot convince the manager that changes are needed, then you are unlikely to be able to change anything in the documentation.

    Let's look at my project, which helped me get the answer “Yes” to the proposal to “demolish” the documentation.



    First of all, every successful project begins with an introduction. You ask correctly, why is this important? If people do not master even the first page, if you do not convince them from the first lines, then it doesn’t matter how cool the arguments you propose next. First you need to convey to them why this is a problem, why it exists. Prepare the reader for what they should expect in 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 sites with documentation.

    To reinforce the arguments, I started talking about the company's goals, for example, to become number one in the cloud providers market, rather than a niche company for geeks. But just writing “we are the best” in marketing materials is not enough to realize this goal, you need to tell the market how to use our product. If no one knows this, then no matter how cool the product you are doing.

    Think about the goals of your company. As the fact that you improve the documentation will affect the profits of the company.

    First, I conducted a content audit. I have listed all of our documentation repositories: what is stored in them, which CMS is used, who is the main audience of each site, who writes documents. Then I recommended which sites should be left, from which to transfer information, and which - to completely demolish.



    The number one priority for a technical writer is the audience. All that we do - we do for the sake of other people, not for ourselves. If you are lucky to have a product or marketing team that segment the audience for you, hold on to it, I did not have such a team.

    I myself divided the audience into four groups by goals:

    • Firstly, these are business owners , people who are interested in acquiring a product, would like to understand what it can do, general principles of work, how to start working with it.
    • The second category is researchers , they are already familiar with the product, but want to learn about advanced functions.
    • Third, these are people who want to solve the 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 may be product managers or engineers who are interested in whether your product can perform any specific function.

    By dividing the audience into these groups, I began to better understand their goals in order to create content that meets expectations.



    The diversity of websites was our priority problem, so the number one goal was to consolidate the content , it was necessary to reorganize it. And this means, first, to understand what is “good” and what is “bad”, what is worth saving, and what is not.

    The second goal is to set up connected templates for different types of content , for example, step-by-step instructions, FAQ, review, so that the reader clearly understands what kind of document he is reading. This has helped us make the content more searchable.

    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 drawing up a request for a document, in it we prescribed mandatory questions that need to be answered, for example, why this document or what information must be included in it. Thus, I was able to avoid the situation when I ask questions like: “What else is the new feature? What does it mean that you urgently need documentation for it, tell us more in detail. ”

    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 feature that no longer exists? How do we plan to archive such materials? Maybe you should delete them completely?



    This is what a “document life cycle plan” is, you must consider every step from creating to deleting a document. For Joyent, this meant that from the moment the idea came up, until the text was written, then from its publication to updating, archiving, or deleting. Each step is logged, there are checks that the content is not lost forever, that warnings and redirects from the old document to the new one are configured. 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 scope, what should be the architecture of the site, what types of content, how the site should look right up to the design.



    Here are a few more points that I will not disclose in detail: this is a schedule, a roadmap, tools that are needed for implementation, an estimate of the time and cost of redoing documents and buying tools, as well as a number of additional questions, for example, do we want open source the documentation? If so, how do we plan to implement this?

    Regardless of whether you end up with a project - long and detailed or small and compact, for example, “Alexandra and Philip want a dog because ...”, it is important that your project reflects clear and understandable reasons why you are planning do so, not otherwise than how you plan to solve the problem and how long it will take.

    We bring the project to life


    So, your project is ready, you impressed the leader, he 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 became templates for future work.



    The time has come to put all the pieces together. The next step after creating and approving a project is a content strategy. In fact, you have already done most of the work.

    Six years ago, I worked as a digital marketing manager for a nonprofit organization. Of course, marketing and technical content are different, the purpose of marketing is to sell, and technical content is to help, teach or assist in the task. However, we can use marketing techniques. Content strategy allows you to achieve consistency in branding. When a user uses products, reads advertising materials, reads documentation, then he should feel the unity of the brand.



    For example, the sidebar on docs.joyent.com looked like this before. Frankly, the services were renamed several times before I appeared at the company, but it was important to make sure that our public product, Triton Compute Service, was updated in the same way.

    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 by naming the Triton images section, now it matches the product name.

    We still have a problem with the company name. We constantly argue with the boss, but more often I lose. Users name the product JPC, in addition, this acronym is used in code. It is difficult to leave this name in the past. But for our part, we can at least adhere to a single product name in the materials.



    Speaking about product naming, it is important to clearly describe the rules for how we name products and components, create an updated glossary in order to achieve consistency.

    It can be part of a style guide to standardize how we talk about ourselves, as well as talk about other brands, for example, Docker. A styleguide can help to agree on what tone, what grammatical constructions, text styles and rules we use. As a result, you yourself will write better, and get drafts of higher quality from your colleagues.

    Another important part of the strategy is actually to “tear down” obsolete 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 there was nothing valuable left.

    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 at Joyent, I was asked to start a completely new project. This meant freezing the content strategy that I carefully built based on product knowledge. Soon, I stopped working on pull requests that I received for a new, task-oriented version of the site with documentation.

    At this point, almost all the sites that we thought were outdated were still online. But I learned from my work and started in a new project from scratch.



    The conclusion is this: sometimes you have to throw all the work into the pipe because of the circumstances.

    You should not feel personal connection with what you are doing, otherwise it will be difficult for you to abandon everything that you have done. Nothing should be so valuable to you. Remember the lessons learned and use in future projects.

    What did we miss


    Despite the fact that I had to leave everything behind, I still learned a few lessons from my work. Namely what I missed.

    The first lesson is user testing . In fact, this should be made the number one priority, along with the budget for tools and the time that you need to spend talking with users about what they like in the documentation and what not.

    Moreover, I would like to talk more closely with colleagues about the same thing. In the end, they are also users of the 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 have pushed through 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 a more general strategy and supporting content?

    There are several ways to integrate colleagues into the process of creating documentation, how to sell them why it is important. If we want them to stop googling answers, create these answers internally.

    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 for management. They need to finish their work first and then help you. Kindly support them.

    Probably the hardest part of this process is to make sure that the experts and engineers understand that this process is important. Even better if the documentation is part of your company's engineering culture .

    Documentation is the task of everyone, not just writers. If everyone is eager to solve user problems, the product is getting better.

    Consider diversity- An important point 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 organization’s culture influences documentation. In fact, writing texts always depends on how we learn, and on how others seem to be learning.

    Diversity is important. Having people with a different background in a team allows you to better take into account different learning models and create better content. And there is a lot of room for growth.



    Let me remind you of the main ideas of this story. Firstly, how to write a cool project for the processing of documentation, secondly, how to take the first steps to implement this project, and finally, about what I initially missed in the process, but you should not. Key findings are:

    • Plans are the key to success. These include design and strategy.
    • But sometimes plans do not mean anything 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've 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 important, as are you. Even if they don’t tell you that.

    Be the shepherd of your herd. Lead users and colleagues to the answers they need.

    Useful materials for the report:


    You can follow Alexandra on Twitter , Github , read her personal blog, or chat with her live on April 26 at KnowledgeConf 2019 after her talk or at the booth of the international community of technical writers Write the docs.

    Also popular now: