The creation and success of a documentation site Tech Writer Developer
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, thedocumentation 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 thedata center gateway and Trend Micro Vision One.
Read More HERE
