Style Guide

Entando Style Guide

Writing Tenets

1. Value the reader’s time more than your own.

2. Justify product existence by demonstrating its value early on in the document.

3. Tone should be author-agnostic. Content must be factual with no bias, interpretations, or speculation.

4. Language should be clear. The goal is for content to be understandable and unambiguous using minimal and simple language.

5. Wording should be concise. Eliminate non-essential or duplicate language and introductory clauses.

6. Iterating and refining documentation as a team should be an integral part of the writing process.

Audience

General guidelines

• Write to your audience.
• Consider that people read technical documents for different reasons and possess varying levels of technical expertise. The target audience dictates the level of detail and technical terminology.

Audience Strategies

1. Strategies for writing to experts

• If your audience consists solely of subject experts, you may not need to give extensive background information or define key technical terms or acronyms. This may pertain to Entando tutorials.
• If your audience includes general experts, provide sufficient background information and define any terms that might be unfamiliar. The parts and processes of concepts should be explained in detail. This pertains to Entando docs.

2. Strategies for writing to mixed audiences

The following strategies are particularly relevant to introductory pages such as Getting Started, Tutorials Overview, and Solution Templates, when the user is first learning about Entando.

• Begin with an executive summary to present an overview of your document in everyday/business language.
• If appropriate, separate the document into sections targeting different audiences. Include in the front matter or introduction a short discussion of which sections are appropriate to each type of reader and to what purpose. Another option is to create separate documents for each audience type.
• Explain all technical terms thoroughly sections that may be read by a lay reader.