Skip to content

General Writing Style

Jump to bottom
Nisrin edited this page Oct 11, 2021 · 5 revisions

It is important to follow a consistent style to create content that looks professional. This page describes the style to follow across all Choreo-related content.

The guidelines here are based on the Google developer documentation style guide. If you want to learn detailed information about any specific aspect of writing, see the Google developer documentation style guide

Voice and tone

  • Follow standard American English spelling.

  • Use active voice. This is important because the active voice is usually clearer.
  • Follow a conversational and friendly tone rather than a formal one.
  • Use present tense rather than future tense. It is important to try and avoid using will where possible, but sometimes it can be necessary to use the future tense when you’re actually talking about the future. For example, in a tutorial or quick start guide, it is ok to use the future tense as follows to describe its purpose:
    In this example, you'll create a service, test it, deploy it, and observe its performance.
  • Write short, clear sentences. The shorter the sentence, the easier it is to read and understand.
  • Use the second person rather than the first person—you instead of we. For more information, see https://developers.google.com/style/person.
  • Be consistent. If you use a particular term for a particular concept in one place, be sure to use that same term, including the same capitalization in all applicable places. Also, ensure that you do not use the same word to mean different things.

  • Use common contractions to bring out the informal tone, but avoid noun + verb contractions and double contractions. For more information, see https://developers.google.com/style/contractions.

  • Define acronyms and abbreviations on the first usage.

Titles and headings

  • Use title-style capitalization for the main title and sentence-style capitalization (i.e., only the first word in uppercase) for all other headings.

  • Maintain branded lowercase proper nouns and other industry standards when used in the main title and headings.
    For example, iPaaS.

  • If you have hyphenated compounds in the main title, capitalize the first word, and capitalize all subsequent words in the compound except for:

  • articles (a, an, and the).
  • prepositions of three or fewer letters (like to and of).
  • coordinating conjunctions (for, and, nor, but, or, yet, and so).

  • Don't skip levels of the heading hierarchy. For example, put a <level 3> heading only under a <level 2> heading.

  • Don't have empty headings or headings with no associated content.

Images

  • Images should be in .png format.

For guidelines on naming images, see image file naming convention

  • Do not overuse images in a document. Images need to be added only when the UI is not intuitive.

  • Do not present new information in images. Always provide an equivalent text explanation with the image.

  • Be sure to adhere to the following when you capture screenshots:

  • Crop images to focus on the area.
  • Highlight UI elements when needed.
  • Mask sensitive information in the UI.
  • Add an ALT tag to every image. Following are a few tips to help you come up with appropriate ALT tags:
  • Make sure the ALT tag provides enough detail for users and search engines to relate the image to the context.
  • Don’t use the same keyword in all images in a page.
  • Limit the ALT tag character count to a maximum of 125 characters.

For example,

  • ![Publish API](../assets/img/services/publish-api.png)
  • ![View latency details](../assets/img/observability/view-latency-details.png)

Lists

  • Use lists when you have information where you want to emphasize important points. If used appropriately, lists can simplify long sentences or multiple paragraphs of content to improve the overall readability.

  • If you use a list, make sure the purpose of the list is clear. You can introduce the list with a heading, a complete sentence, or a fragment that ends with a colon.

  • Avoid having more than 10 items on a list. It is best to limit to 6 or 7 items, but you can go up to a maximum of 10 items.

  • The common types of lists we generally use are bulleted lists and numbered lists.

Bulleted lists

  • Use a bulleted list for items that have something in common but don’t need to appear in a particular order.
    
For example,

Choreo supports the following trigger types:

  • API
  • Manual
  • Schedule

Numbered lists

  • Use a numbered list for sequential items (like a procedure) or prioritized items (like a top 10 list).

Clone this wiki locally