Improving Tech Elevator's technical curriculum

Technical Writer · 2020 · 6 months · 5 people · 4 min read

Reduced documentation errors by 71% by implementing a linter, freeing up time for structural reviews and testing.

Overview

As the sole technical writer for Tech Elevator's curriculum team, I implemented Vale, a customizable documentation linter, to catch style and grammar errors earlier in the development process. This allowed me to focus on larger structural issues and do my own user testing and validation.

Problem

Developers were submitting content with style and grammar issues, such as typos and inconsistent voice and tone. As the sole technical writer, I spent more time fixing typos than I did performing larger, structural reviews of the content. I couldn't afford to be bogged down by copyediting work.

Approach

I researched and implemented Vale, a linter that integrates into VS Code. This work included building custom rules based on the Google Developer Documentation Style Guide and creating a glossary of project-specific terms. To encourage team-wide adoption, I trained the developers on how to install and use the linter on their machines. As they drafted content in VS Code, they ran Vale to flag any typos and wording choices. This enabled the developers to identify and fix any issues before sending the documentation to me for editing. I maintained the project glossary and added new rules as the curriculum evolved.

Challenges

  • Sole technical writer on the curriculum team (no backup)
  • Tool had to integrate with developer workflow to encourage adoption

Key Tasks

Implement Vale to shift quality control left into the development workflow

Reasoning:

Rather than slow down reviews by sending drafts back for rework, I put the tool directly in developers' hands. This caught errors before submission and kept curriculum releases on schedule.

Alternatives considered:
  • Reject drafts and send back for rework (would have delayed curriculum releases)
  • Use tools outside the dev workflow (would have added friction and reduced adoption)

Customize Vale with project-specific terms

Reasoning:

Vale provided an implementation of the Google Developer Documentation Style Guide (GDDSG) for us to use. However, there were some terms that we used that weren't included in the GDDSG, so I developed some custom rules. These rules enforced consistency in terminology, brand voice, and style.

Alternatives considered:
  • Use Vale with default rules (wouldn't catch voice/tone issues)
  • Create a manual style guide (developers wouldn't consult it while writing)

Train developers directly on Vale usage

Reasoning:

After I implemented Vale for our curriculum repositories, I held some training sessions with the developers. I did some demos, walked them through the installation process, and explained how to run Vale on their drafts. These training sessions increased team-wide adoption and showed developers why consistency mattered in our curriculum.

Maintain Vale configuration and glossary over time

Reasoning:

As our curriculum evolved, I updated rules and terms to stay relevant. During our sprint planning, I updated the team on any changes to Vale rules or terminology. This showed developers I was invested in the tool and kept it useful.

Tech Stack

  • Vale (linter)
  • Visual Studio Code
  • YAML
  • Google Developer Documentation Style Guide
  • Bitbucket

Impact

  • 71% reduction in documentation errors across the curriculum
    Error reduction
  • Critical style and grammar issues caught before submission
    Critical errors eliminated
  • Shifted from line-level copyediting to structural review and testing
    Time freed for higher-value work
  • Developers actively used Vale during drafting; positive feedback on usefulness
    Developer adoption

The linter fundamentally changed my workflow. Instead of spending hours fixing commas and inconsistent voice, I could focus on structural issues. Additionally, the extra time allowed me to test the curriculum. I tested the tutorials and exercises as a student would and identified major bugs that would have reached students and instructors. The curriculum improved in quality and shipped on schedule.

Learnings

  • Shifting quality left is more effective than gatekeeping at review
  • Doc tools adopted by developers need to integrate seamlessly into their workflow
  • Documentation testing can surface critical bugs that escape code review

Notes

By implementing Vale, I freed myself from line-level copyediting work and had the bandwidth to do curriculum testing. I started running through the tutorials, testing and reviewing code samples, and looking for any issues developers missed during their technical review.

I eventually realized that I wasn’t just editing technical curriculum anymore. Now, I was testing the curriculum, breaking it, finding any usability gaps. I caught critical bugs that would have reached students and instructors.

This experience stayed with me. When I moved to VMware, I took every opportunity to test the products I documented and understand the user experience firsthand.

All projects