Multi Cloud
The creation and success of a documentation site
Gain a better understanding of why collaboration between developers and writers is necessary to create a successful documentation site
Save to Folio
The value of good documentation cannot be overstated. Customers are known to go to a less feature-rich competitor if their software is easier to use. Documentation sites are often the first place customers look for information about software, which is why the documentation has to be reliable and easy to understand. For developers, if you haven't correctly documented a feature, it may as well not exist.
These were all points that we kept in mind when creating the Trend Micro Cloud One™ documentation site. This documentation site is a single source for any and all of your Trend Micro Cloud One questions. It hosts service-specific documentation for Conformity, File Storage, Security, Workload Security, Container Security, Application Security, and Network Security, and will host any future service documentation as well. It also includes documentation for common content across all services, like What’s New, User Management, and Billing.
Why was a new documentation site needed?
Trend Micro Cloud One is an automated, flexible, all-in-one security solution that requires an automated, flexible, all-in-one documentation site. Multiple, diverse teams from across the globe integrated together to create one unified solution. Each of those teams came with their own documentation processes, requirements, and wish lists. At any given time, writers used multiple processes that involved MadCap Flare, WordPress, GitHub Pages, Adobe Acrobat, and Jenkins to edit, review, and publish the documentation site. Each product had a separate and unique process from the other, and writers who worked on multiple products were forced to understand and work in multiple streams.
To support the writers, Trend Micro activated a team of dedicated developers to help ease the burden of maintaining a documentation site. The developers are responsible for creating, building, and maintaining the site. Their team is rooted in DevOps practices and regularly works with publishing pipelines. Essentially, they support writers and, by proxy, customers.
However, different writers from across the globe are not so easy to support when each team has their own process, culture, and tools. The development team needed to create a documentation process that was lightweight, customizable, and easy to use.
Markdown turned out to be the perfect solution, and MkDocs was the tool that brought that solution to life.
MkDocs supports both Markdown and HTML, so writers have the opportunity to simplify their documentation without any fear of losing some of the more complicated layout features that HTML provides. For developers, MkDocs provides a base package that offers the ability to add customizable plugins easily. This means that almost any ask the writers have, the developers can provide.
The pipeline that supports MkDocs also allows for flexibility in processes. The pipeline can build a unified site from independently structured repositories and supports custom themes that were developed to use with MkDocs. It also supports the use of common tools such as Slack for build notifications and Amazon Web Service (AWS) for accessibility via the cloud.
How does it work?
Two processes are working simultaneously anytime a documentation update is required:
- The writing process
- The automation process
The writers cover the writing process (no surprise there), while the automation process operates at a nearly invisible level to the writers. Writers are only responsible for researching, writing, and reviewing their work. That’s it. Meanwhile, the automation process supports each of these tasks by creating review builds and publishing the documentation site.
For example, let’s assume a writer finds a broken link on the site.
To fix the issue, the writer would:
1. Edit the article in Markdown.
2. Push the changes to Github and then wait for a Slack message that indicates if the build was successful.
3. Review the development builds to ensure the changes appear as expected.
4. Create a pull request (PR) in GitHub and have the PR reviewed by another writer. After it’s approved, merge it.
In a few minutes, the documentation site is updated with the live content.
What did developers learn?
For a developer, it’s rare that you work closely with the documentation team, besides giving them some information about your feature that you’re currently working on and that needs to be documented. However, by having the opportunity to work closely with writers and getting the chance to understand their process, you can learn a lot.
Writers often struggle with a lack of resources
Writers sometimes struggle to fit into software companies. Typically, there are only a few writers on a team with upwards of hundreds of developers. Writers are the minority. When writers are a part of research and development (R&D), their requests or needs can sometimes go ignored, often unintentionally. Resources are more typically allocated to developers, with a focus on how to improve the developers’ process. The writers’ process can receive very little attention.
Writers’ influence is felt everywhere
Despite the lack of resources, writers’ influence can be felt throughout the company. They’re responsible for documenting features, but they’re also often involved in user experience (UX), marketing, support, and sales. However, writers’ value can sometimes be overlooked in favor of celebrating significant feature developments or major sales.
Writers are not developers
Some things that are obvious for a developer might be difficult or new for a writer. For developers, if something in your process isn’t working to the best of its abilities, you can generally change that thing with relative ease. For writers, this often isn’t the case.
Writers consistently add and create value to products, but because they don’t have the same knowledge as developers, their processes can occasionally get left behind. That’s why it’s so important to have a team of developers who support the writers and see gaps in their process. Those developers should be in constant communication with writers to understand their needs, whether it’s with simple tips like using shortcuts in Git, or more complicated requests like adding customized plugins.
Speed is key
Everyone working in a software company appreciates fast build-times, but no one more so than writers. For developers, it’s not uncommon to wait over an hour for builds to complete. For writers, that kind of wait time is unacceptable. The documentation site has to be updated within a few minutes with new and reliable information. The faster that information gets out, the better. In one day, writers might update the documentation site every three hours. In a week, they could update the site almost 50 times. Having the ability to quickly and easily make changes is absolutely essential for maintaining first-class documentation.
Every team has its own culture
One of the cool things about working with writers is that you’re exposed to a range of different experiences, work cultures, and opinions that you otherwise might not be. Developers often work in a single environment and can spend years focusing on one particular feature. However, working with writers means you have the opportunity to work with a wide range of different teams from across the world. This can provide insight into how other teams work and introduce you to different cultures or values within the software community, or even within your own company.
What were the benefits of this project?
If you’ve read this far, you probably assume you already know what was accomplished—a reliable, flexible documentation site that allows writers from different teams to contribute to the documentation. And you’d be correct; that was accomplished. However, as part of that accomplishment, a few less obvious things were achieved as well.
Better builds
Not only are the builds significantly faster than before, but they also provide more value. For example, writers can now review a preview build of precisely what’s going to appear in the live documentation site, so they can make sure the content looks good and is easy to read before it’s published. This also makes reviewing the content significantly easier.
Markdown
All hail Markdown—arguably the simplest markup language available. Unlike HTML or XML, which can take a lot of practice and can be incredibly tedious to write by hand, Markdown is easy to learn and implement. It’s also incredibly simple to read and can be copied and pasted throughout different platforms without requiring a ton of interference to make it legible.
Developers and support engineers’ contributions
Because the documentation site is written in Markdown, it allows developers and support engineers (SEs) to quickly make changes directly to the articles without worrying about navigating a more complicated markup language. Writers are responsible for documenting features or more complex processes; however, sometimes an article only requires a minor fix. Instead of developers or SEs finding the problem, figuring out the solution, contacting a writer, waiting for a writer to make the change, then reviewing the change, they can simply locate the document and make the change themselves, then send it to a writer for approval. This saves a lot of time and ultimately helps make the documentation process faster and more reliable.
Writers have more time to focus on what they do best – writing
Ultimately, all of the above points help to save writers some time. Rather than waiting on builds, attempting to maintain sites, wrestling with HTML or XML, or getting interrupted by support requests, they can more meaningfully spend their time writing articles and continuously adding value to the product. This means the writers are happy, the developers are happy, and the customers are happy.
Why can you rely on the documentation site?
As a Trend Micro Cloud One user, the documentation site is often the first source you might go to for information about what a particular feature does, how it works, and how you can enable it in your system. The documentation site contains a wealth of information about the various products to help you protect your environment. The documentation pipelines are reliable and well-maintained, so you can be sure that you have the most up-to-date information available and that it’s easy to navigate and understand.
For developers, the benefit of a reliable documentation site can be even more important. Without a documentation site, the feature you might have spent months creating would risk being unusable or ignored. The better the documentation process, the more time you as a developer have to create new features that benefit customers, rather than fielding questions from support or angry users.
Having a reliable, automated, and flexible documentation site is critical to creating excellent documentation. And, ultimately, excellent documentation benefits everyone.
About the Authors
Stephanie Melnik started at Trend Micro as a backend developer in 2017; however, after working on the Workload Security API, she became more interested in the frontend and being involved in the documentation project. Through collaborating with a development team that focuses on supporting the documentation process, she’s had the opportunity to work in a genuinely DevOps environment and learn about ops, architecture, UX, developer relations, frontend, and publishing.
Sophie Gervais has worked as a technical writer for Trend Micro™ Deep Security™ Software and Trend Micro Cloud One since 2017. Throughout that time, she’s been intimately involved with the writers’ process and has witnessed the continuous improvements the teams have made. So far, she’s worked on Deep Security, Workload Security, and Application Security. She also helped restructure and modernize the release note process, and documented new and innovative features like the data center gateway and Trend Micro Vision One.
