Progress DevTools Style Guide:
An Introduction

This Style Guide contains best practices and recommendations for writing end-user documentation for the DevTools products at Progress Software. The Progress DevTools products are all Telerik and Kendo UI suites, for example, Kendo UI for Angular, Telerik UI for Blazor, KendoReact, Telerik UI for ASP.NET Core, and so on.

These recommendations have been collected based on the most frequent grammar and style issues we as technical writers have encountered throughout the years. In the process, we also addressed feedback from and were supported by members of the Support and Dev teams.

Disclaimer: While the application of these Style Guide recommendations is optional, it is desirable—following them systematically ensures consistency across the documentation sites and provides for high-quality content.

In This Article

• Intended Purpose
• Flavors and Intended Audience
• About the Content Organization
• Missing Information
• Adding Your Contribution
• Providing Feedback
• Next Steps

Intended Purpose

The idea behind embracing and placing these guidelines in a single location was to:

• Establish shared standards for creating and maintaining the DevTools documentation.

  Apart from the officially established language conventions, fixed content-authoring rules do not exist. However, writers across the globe agree that good documentation follows some universally accepted guidelines industry-wide.

• Increase the quality of the DevTools documentation and set up a common basis for quality assessment.

  Standardized documentation is logically structured, worded, and presented, and is easier to elaborate on and improve based on adopted KPIs.

• Improve customer support experience.

  Consistent, concise, and well-structured user-assistance information boosts customer service and customer support quality and optimization. High-quality end-user documentation decreases front-line customer support and adds up to the overall customer experience and satisfaction. The authoring of high-quality content requires commitment and dedication.

• Coordinate the authoring efforts and propagate an agreed process for content creation.

  You need to possess thorough knowledge about the product, its features, and the way they blend. This knowledge, in turn, has to be converted into a comprehensive, human-readable, and functional format from a user's perspective.

• Facilitate the training of new team members.

  New Support Team hires benefit from becoming aware of the recommendations in this Style Guide as often it is the Support Teams who initiate the creation and update of the product documentation.

Flavors and Intended Audience

The Progress DevTools Style Guide presents its topics in the following flavors:

• Cheat-sheet thematic essentials: the topic selection—Organized as a user-friendly, single-page, quick-reference guide, the Cheat sheet lists the most frequent issues and demonstrates them with examples and a minimum set of explanations.

  Intended audience: All Progress employees who face the challenge to write end-user product documentation as well as users who want to improve the product documentation by creating Pull Requests to product documentation repositories.

• Style Guide full-blown library: the complete collection—Split into articles, the full Style Guide collection elaborates on specific topics and contains information on grammar, explanations on adopted best practices, and examples.

  Intended audience: Not only technical writers, but also the enthusiasts who are interested in why we've set up a rule the way it is.

About the Content Organization

These guidelines are distributed in articles related to the type of content they refer to. For example, the recommendations about how to present information in bullet and numbered lists are collected in the Lists article.

For easier navigation and information retrieval, each article has an In This Article section with the list of the linked sections inside that article. For example, see the section mapping of the current article.

Most articles, as their minimum, contain a General (or similar) and a Guidelines section to separate the more theoretical from the more practical information about their topic. For example, see Personal Pronouns.

Topics which, to explain certain recommendations, need to elaborate a bit more on grammar, introduce a Grammar Pool section. For example, Basic Rules and Guidelines talks about the Active vs. Passive Voice; the Grammar Pool section provides information about what the Active and Passive Voices are so that the reader can much more easily realize why one is better to use than the other and understand the examples that follow at a glance.

The Cheat sheet is unique in its structure and presents an all-topic selection of the most frequent use cases we as technical writers come across at the DevTools division.

Missing Information

While comprehensive, the Progress DevTools Style Guide is not exhaustive.

If you can't find the information you're looking for throughout the Progress DevTools Style Guide, try the Microsoft Style Guide. If there's a conflict between the Progress DevTools Style Guide and the Microsoft Style Guide, stick to the recommendations in the Progress DevTools Style Guide.

If you want to add a missing piece to the Progress DevTools Style Guide, consider adding your contribution or providing feedback.

Adding Your Contribution

In agile and dynamic environments, Style Guides evolve over time to embrace new channels, mediums, product lines, and company strategies.

Therefore, you are much welcome to iterate on the content in this Style Guide by minding the following steps:

1. Create a feature branch when making any changes to the Style Guide.
2. After you've made your changes, rebase with master.
3. Submit a Pull Request for review and approval.

4. Before merging the Pull Request, rebase again.

   If the Pull Request contains two or more commits, do not squash them. Execute the merge command instead, to preserve the branch history on Git.

Providing Feedback

To share your feedback about an existing documentation page, use the Is this article helpful? form on the right side of each topic. To enable us to operate on your feedback and implement the improvements, provide specific information about what's not OK.

For questions and comments related to the Style Guide, send an email to [e-mail].

And, having said all that, happy authoring!

Next Steps

• The cheat-sheet essential selection
• About the basic rules and guidelines when creating documentation