Style Guide for Documentation and User Interface Text

About This Guide

The Style Guide for Documentation and User Interface Text is an essential resource that establishes consistent terminology and provides clear usage guidelines for all user-facing text. This includes text that appears in the user interface of software products as well as text in customer-facing documentation such as user guides, online help, and tutorials.

By adhering to the standards and best practices defined in this style guide, technical writers can ensure that the information we deliver to users is clear, accurate, and easy to understand. The style guide promotes consistency in language and formatting across all user-facing materials, which enhances the professional quality of our content and makes information more accessible and usable for our customers.

• For general style questions not covered in this guide, we refer to The Chicago Manual of Style or the Microsoft Manual of Style for Technical Publications.

• For questions related to spelling and word usage, consult dictionary.com, which is based on the Random House Unabridged Dictionary, as the authoritative source.

Benefits of Standard Terminology and Usage Guidelines

Standard terminology and usage guidelines provide several key benefits for technical content and user interfaces:

• Consistency: By following a set of usage guidelines, content creators can produce materials that adhere to a uniform style and voice. This consistency helps create a cohesive user experience across all content and interfaces.

• Professionalism: Adhering to style and usage guidelines elevates the quality and polish of user-facing text. Consistent, properly used terminology makes documentation and UI text appear more professional and credible to users.

• Learnability: When all content and user interfaces employ the same terminology and style conventions, users can learn and navigate the system more quickly and easily. Predictable language patterns allow users to focus on tasks and concepts rather than deciphering inconsistent text.

Target Audience

This guide is intended for professionals involved in creating applications, documentation, and training materials, including:

• Technical Writers: Professionals who write user guides, API documentation, release notes, and other technical content to help users understand how to use a product or service effectively.

• Curriculum Developers: Educators who design, develop and evaluate educational curricula and training programs. They create lesson plans, course materials, and assessment tools optimized for student learning.

• Trainers: Experts who teach skills or knowledge to employees, customers or other learners through in-person or online training sessions, workshops, or seminars. They use instructional techniques to effectively convey information.

• Editors and Proofreaders: Publishing professionals who review, revise and polish written content to improve clarity, coherence, consistency and adherence to editorial guidelines before publication. They catch errors and ensure high quality.

• Product Managers: Leaders who oversee the planning, development and launch of products. They define the product vision, prioritize features, and coordinate across teams to deliver a successful product to market that meets user needs.

• Developers: Engineers who design, code, test and maintain software applications and systems. They collaborate with cross-functional teams to implement technical solutions that power digital products and services.

• User Experience (UX) Professionals: Experts who research, design and optimize the end-to-end experience users have when interacting with a product or service. They conduct user testing, create wireframes and prototypes, and define intuitive interfaces and smooth user flows.

Styles

Jargon and Cliches

it is important to communicate complex concepts and information clearly and effectively to your target audience. One key to doing this is to avoid using jargon and cliches in your writing. Jargon refers to specialized or technical terminology that may be unfamiliar to readers outside a particular field. Cliches are overused words and phrases that have lost their impact through excessive use.

Examples of jargon and cliches to avoid in technical writing include:

• Cutting edge

• Ease of use

• General-purpose

• Grow your business

• Hands-on

• Innovative

• Intuitively

• Leverage (as a verb)

• Paradigm

• Powerful feature

• State-of-the-art

• Robust

• User-friendly

• Total solution

Instead of relying on jargon and cliches, strive to find clear, precise, and original language that effectively conveys your ideas to the reader. Whenever possible, translate technical jargon into plain, simple words that will be easily understood. When dealing with a highly technical audience, jargon may sometimes be necessary and appropriate. In those cases, make sure to clearly define the terms and use them consistently throughout the document.

By avoiding cliches and either eliminating or carefully using and explaining jargon, you can ensure your technical writing is as clear and effective as possible in communicating key information to your target audience. Your writing will be more engaging and will leave a stronger impact.

Paragraphs

Be Concise

Write using as few words as possible while still conveying the necessary information. Focus the content on the essential steps users need to complete their tasks. Ruthlessly eliminate any redundant or extraneous information. Keep paragraphs and sentences short and to the point.

Make Content Scannable

Users rarely read documentation word-for-word. Instead, they scan to find the specific information they need. Design your paragraphs to facilitate scanning:

• Lead with the most important points first

• Use bulleted lists to break up multiple pieces of information

• Place actionable steps before explanations

• Assume users stop reading after finding the information they need

• Use "See Also" links at the end to point to related topics

Avoid Walls of Text

Strive to cover only a single topic in each paragraph. Write using simple sentences that readers can easily understand on the first read-through. As a rule of thumb, keep the average sentence length under 17 words.

Use transition words and phrases to maintain a logical flow between sentences and paragraphs. Some useful transitions include: also, in addition, moreover, consequently, however, although, for example, next, first, finally, in contrast. Avoid stringing together multiple one-sentence paragraphs in your writing.

Author

Edward Wong