Joseph Perez, Technical Communicator

After over seven years in technical communication, I am often asked what keeps me motivated in a field that is, by definition, most successful when it is invisible. If a developer uses my documentation to build a plugin for Grafana, integrate an EA API, or navigate Google Maps platform, they aren’t thinking about the writer. They are thinking about their own success. For me, that is exactly where the satisfaction lies.

The Journey That Led Me Here

My path to technical writing began long before I knew this profession existed. As an early computer enthusiast, I spent countless hours pounding out codes of BASIC on my Commodore 64, captivated by the magic of making machines respond to human instructions. That early fascination never left me.

This passion for technology drove me to teach myself essential C programming years ago. While I never progressed to the point where I wanted to join a software development team, I discovered something unexpected: I felt remarkably comfortable documenting APIs. This realization led me to document an API in C and C++ for a speech software company, create comprehensive documentation for a SOAP API at a database company, and edit a book on C# programming for Microsoft Press. These experiences hinted at my true calling: bridging the gap between complex technology and the people who need to use it.

Although I pursued other professional paths for quite a while, I returned to technical communication seven years ago to work as a contractor for Google. Since then, I’ve genuinely enjoyed the challenge of learning how technology is evolving, understanding how it is transforming our world, and playing a small but meaningful role in making that progress accessible and possible for others.

The Beauty of the “Bug Fix”

Early in my career, I realized that technical writing is fundamentally a form of engineering. There is a deep, quiet satisfaction in the “unseen” maintenance tasks that most people never notice but that make all the difference:

• The Repository Cleanup: At Microsoft, I initiated over 200 pull requests to fix bugs and improve documentation quality, systematically eliminating obstacles that would have frustrated countless developers.
• The Migration: At Electronic Arts, I consolidated a massive, fragmented documentation set into a single, searchable knowledge base, transforming chaos into order and saving developers hours of searching for critical information.
• The Content Audit: At Google, I performed the exhaustive audits necessary to raise a Doc Health Score by 500%, meticulously reviewing and refining content to ensure accuracy and usability.

These aren’t “glamour” projects that earn recognition at company meetings. They are the digital equivalent of clearing a path through a dense forest—unglamorous, painstaking work that creates value precisely because it removes friction. When I remove a broken link or clarify a confusing paragraph, I am removing a barrier for someone else, enabling them to move forward with their work unimpeded.

Solving the Puzzle

Technical writing allows me to be a perpetual student, which perfectly suits my lifelong appetite for learning new technologies. One day I am researching logistics systems for Amazon FBA, and the next I am covering the latest enterprise software trends for SAPinsider or ERP Today. I find fulfillment in taking a chaotic pile of information and organizing it into a logical, elegant structure that serves the user’s needs.

This constant learning keeps the work fresh and intellectually stimulating. Each new technology, each new API, each new platform presents its own unique puzzle to solve, its own particular challenges in translating technical complexity into clear, actionable guidance.

The Human Element

Ultimately, my work is fundamentally about empathy and human connection. Whether I’m documenting open-source observability tools for 20 million users at Grafana Labs or writing for a global audience at Amazon, I am advocating for the person on the other side of the screen—someone I’ll likely never meet but whose frustration I can prevent, whose time I can save, whose success I can enable. There is a profound sense of purpose in knowing that my work helps a developer finish their task a little faster, with a little less frustration, so they can get back to what they love doing most.

As a Harvard University graduate with honors, I could have chosen many paths involving language—journalism, academia, creative writing, or communications. I chose this one because I believe that clear, accessible documentation is one of the most important “features” any software product can have. That’s what drives me: the opportunity to unlock technology’s potential by making it comprehensible, accessible, and genuinely useful to the people who need it.

For years, the standard for technical documentation was the monolithic CMS systems designed for “content” in the abstract, but often divorced from the actual environment where software is built. My journey across organizations like Google, Microsoft, and Grafana Labs has fundamentally shifted my perspective toward docs-as-code workflows.

Why the Shift?

Early in my career, I saw the friction caused by siloed documentation. When docs live in a separate web portal managed by a non-developer editor, they naturally drift away from the source code. By adopting tools like Git, Markdown, Hugo, and Docusaurus, we bring documentation into the developer’s native habitat. This allows developers to take responsibility for documenting their own work, and it allows technical writers to be more fully integrated into the team’s development process.

For technical writers transitioning from traditional CMS platforms, this shift represents a fundamental reimagining of your role within the development team. You’re no longer the downstream recipient of incomplete information; you become an embedded collaborator who can see, understand, and influence the code alongside the documentation. This visibility transforms the quality and accuracy of what you produce.

Treating documentation like code means it follows the same lifecycle as the product:

Version Control: Using Git allows for precise tracking of changes and the ability to revert errors instantly. Beyond basic rollback capabilities, Git enables powerful branching strategies where documentation updates can be developed in parallel with features, tested in staging environments, and merged only when the feature ships. This synchronization prevents the common problem of documentation being published too early or too late relative to feature releases.

Peer Review: At Google and elsewhere, I submitted substantial change-lists or pull-requests (PRs), ensuring every word was vetted by engineers through the same code review process they use for features. This peer review culture catches technical inaccuracies before publication and creates shared ownership of documentation quality. Engineers become invested stakeholders rather than reluctant contributors. The review process also serves as an informal mentorship opportunity whereby junior engineers learn from seeing how senior developers critique and improve documentation, while writers gain deeper technical insights through reviewer feedback.

Automation: CI/CD pipelines can run linters to check for broken links or style guide violations before a single page is published. At Grafana Labs, we used linters to check for divergences from the team’s Writers’ Toolkit (our style guide). Advanced teams integrate Vale or other prose linters to enforce terminology consistency, readability metrics, and brand voice guidelines. Some organizations even run automated accessibility checks, ensuring documentation meets Web Content Accessibility Guidelines (WCAG) standards before deployment. This automation amplifies editorial judgment by catching mechanical errors that would otherwise consume review cycles.

Impact on Developer Experience

At Grafana Labs, I collaborated with a director of development and another engineer to lead the building of a developer documentation portal (grafana.com/developers) designed for discoverability. At the open-source observability company, engineers had built several distinct silos of information for their separate projects, but this made it frustrating to find what you needed. The company’s divergent threads for plugin building, specifications, and design system were brought together under one umbrella. You can read all about our journey to creating the portal at “The Grafana developer portal: your gateway to enhanced plugin development.”

When documentation lives in the repository, it becomes more of a “living” entity. Paid developers and open-source contributors alike are more likely to contribute updates or suggest edits when they can simply open a PR. The psychological barrier to contribution drops precipitously when the workflow mirrors what developers already do dozens of times per day.

Moreover, having documentation in the repository enables powerful cross-referencing. Code comments can link directly to documentation sections; documentation can reference specific lines of code with permanent links that update as the codebase evolves. This bidirectional relationship creates a cohesive knowledge ecosystem rather than two separate information silos.

Conclusion

The transition is about a transformation of documentation culture. It’s an acknowledgment that documentation is a first-class citizen of the software development life cycle (SDLC). When we treat docs like code, we bring software engineers and writers together to build better products. This cultural shift manifests in tangible ways: documentation tickets appear in the same sprint planning as feature work, documentation coverage becomes a release criterion, and engineers budget time for documentation the same way they budget for testing.

In the past 7 years since I first started using the docs-as-code workflow, I’ve learned that it isn’t just about version control or static site generators. It’s about breaking down the artificial barriers between code and documentation, between engineers and writers, between the product and its explanation. When those barriers dissolve, both the code and the docs improve, creating a virtuous cycle that benefits everyone: developers, writers, and most importantly, the users trying to understand and use what we’ve built.