DevTools Style Guide Goes Public

The Progress DevTools documentation style guide is now open to the public. Learn from our process and final product the importance of consistency.

Developers are unequivocal: Well-maintained documentation is essential for them to successfully adopt and use software tools. The challenge we face as a software company is: How do you make sure that a portfolio of 16+ software products developed by multiple teams and used across the globe are not only well documented, but also have documentation that looks and sounds consistent and is easy to understand, without being overly simplistic.

In February 2022, the Progress DevTools documentation style guide joined the family of publicly available company style guides and is now available to all our existing users and future customers. As it contains some guidelines universally accepted by technical writers worldwide, parts of it can also be used by everyone who creates and maintains online content, and all kinds of organizations can benefit by setting it as a starting point for establishing their own guide of writing rules.

About the Style Guide

Quality product documentation adheres to some basic writing practices that ensure published content is easy to read, understand and learn from. Having to fix identical issues when supporting our colleagues in their content maintenance efforts, the team of technical writers at Progress set on establishing a collection of rules that provide for product documentation consistency across all DevTools teams.

The Progress DevTools documentation writing guidelines are used to create and expand the documentation for all our developer productivity tools from our .NET and JavaScript UI component libraries to Fiddler and Unite UX.

The hands-on implementation of these recommendations is an ongoing process and requires continuous effort. Exceeding our most daring expectations, the dev teams have embraced the challenge—not only are they applying the guidelines, but also prioritizing major quality documentation projects such as a general revamp of mature product content.

The DevTools style guide contains two types of best practices that we, as documentation creators, apply when creating, editing or maintaining the product documentation:

• Recommendations that are globally agreed upon by the technical writers. For example, we use numbered lists for steps in a procedure.
• Concrete guidelines based on the specifics of our products, the technology we use, our documentation storage containers and more. For example, we have set some common rules for the metadata tags we include at the beginning of each article for SEO purposes (or front matter) and have agreed on templates for some of the commonly used resources such as the Knowledge Base articles.

The Story

We have had the DevTools style guide for seven years. At the heart of its creation was the task of setting the outlines of consistent documentation across products. Using a visually logical structure drastically decreases the time users spend orienting in the content they land on and cut it down to around seven seconds.

We, technical creators from various product teams, worked for more than a year to sift through the most frequent use cases that needed addressing such as approaches for directly addressing the user and avoiding the Passive Voice to add more clarity.

We had to find the balance between what was important for providing beneficial documentation to our users, setting rules that ensured technical communication at the highest level, and winning the support of our colleagues to follow them. It took months of work, but eventually the DevTools style guide was ready for internal usage, and we have been using it for years.

And then, we decided to publish it.

Why Make It Public?

We consider documentation as a product on its own, and it is subject to constant care, iteration and improvement. We want to provide all users with the opportunity to have a say and explicitly state what content they expect and would like to find—from the structure of an article to the essence of its content. It has always been our policy to let users transparently contribute to our documentation through GitHub Pull Requests, but now they have the blueprint to do it more easily, smoothly and consistently.

We are serious not only about our products, but also about our documentation. The Pushing the Envelope category award in the 2020 ASP Best Websites Competition that Progress won proved it by acknowledging our efforts in boosting our product documentation.

Why the Guidelines

Never ask a technical writer why product documentation should be consistent. You are playing with fire and risk entering an endless argument.

Jokes aside, cognitive science has it: When learning about a topic, the brain perceives information faster and easier when it receives the same type of content in the same way. Therefore, one of the guidelines advises that we use parallel structures when we list logically equivalent items.

For example, if you start the first entry with a verb, start all entries with a verb. Along the same lines go the second and third recommendations: If you start the entry with a capital letter, capitalize all entries; if you end the first entry with a period, terminate all with a period. The following is a simple demonstration:

Apply any of the following approaches:

• Update the app.
• Reinstall the app.
• Remove the app completely.

Apart from an intuitive visual representation of a topic’s logical flow, we have established some templates that meet the specifics of the article type and provide information users need to solve a specific scenario or handle a particular problem.

Perfect examples are the Knowledge Base (KB) articles, which thematically include information about how to achieve a desired scenario or work around a current state of configuration, and how to handle issues that relate to troubleshooting.

For instance, in its body, a how-to Knowledge Base scenario includes the description of what a user may require plus its implementation in the project. On the other hand, a troubleshooting Knowledge Base topic provides the error message users may get, if applicable, plus the cause for its occurrence in addition.

What You Can Do

Contribute to the content. This is how you can help us provide targeted and helpful information that helps users achieve their goals effectively. Based on this collaboration, we will be able to identify what developers require from the documentation and then work on actionable steps to provide it more precisely.

For comments and suggestions on the DevTools style guide itself or with general documentation improvement ideas, reach out to us at techwriters@progress.com.

To submit a suggestion for enhancing an article in our documentation, click the Improve this article link on the page to open a Pull Request, or select the Contact Support option for the Support team to lend a hand with the process going forward.

You can always submit your valuable feedback on a specific documentation page through the Was this article helpful? Yes/No form so that the teams can operate on it and update the content, respectively.

Having said that, happy reading!