style-guide.adoc

TigerGraph Docs Style Guide

This style guide is intended for use by contributors, not necessarily end-users. It provides general guidance to anyone who contributes to TigerGraph’s documentation.

Intended audience

This style guide is intended for use by any contributors that are writing documentation for TigerGraph, including software engineers. This guide can help project contributors to communicate clearly and consistently in TigerGraph’s documentation

Our preferred style guide

We have adopted the Google developer documentation style guide for TigerGraph documentation.

For a quick summary, see the Google style guide highlights. The rest of this document describes our project-specific customizations to Google’s guide.

We use standard American spelling and our preferred dictionary is the American Heritage Dictionary.

Note	If you see an instance where the style guide isn’t followed, feel free to edit it to be consistent with the style guide. However, if you make an edit, please make sure you correct all occurrences in the same document.

Key points

• Function of pages

  • Consider entries from the point of view of someone wanting to achieve a task. If the documentation doesn’t help the user achieve a task, it is ineffective. Do not list out each function and its location in the UI, but rather explain their use cases.

• Repetition

  • Some repetition is ideal in a tutorial context. Otherwise, avoid giving extra detail (such as the location of buttons) more than once or twice in an article.

• Screenshots

  • Screenshots should give enough context for a user to find the relevant location on the screen. Using many screenshots in a single article breaks up the flow of text and will cause extra work in case of a UI update. Use screenshots only when concise instructions are not enough to direct users to their goals.

• Timeless voice

  • Avoid phrases that hint at ongoing development of the product such as "currently" or "for the time being." A detailed list of such phrases can be found on Google’s style guide here.

Exceptions

There are a couple of style choices in our documentation that are different from the Google style guide.

• Titles

  • Document titles use title-style capitalization instead of sentence-style.

• Commas

  • The Oxford comma is not used in a list: "A, B and C" is preferred over "A, B, and C."

Glossary of preferred terms

Preferred term	Avoid these terms	Explanation
the TigerGraph Linux user	the tigergraph user, tigergraph user	Users can change the default name for the TigerGraph Linux user. Additionally, "tigergraph user" is very ambiguous.
TigerGraph Cloud	TG Cloud, Tg cloud	Always use the full name or official acronym to refer to products.
For example	e.g.	Avoid non-English words; Too many people mix up e.g. and i.e.
that is	i.e.	Avoid non-English words; Too many people mix up e.g. and i.e.
can, might, must, we recommend	should	Google Style Guide - Should
privileges (plural form)	privilege (singular form)
the data is	the data are	Google Style Guide - Data
on-premise, on-prem	on-premises
tarball, .tar file	tar file	Describe common file extensions without the period
log in (verb), login (noun or adjective)	Avoid inconsistent usage	Google Style Guide - Login
repository	repo	Google Style Guide - Repo
Spell out numbers from zero to nine in most cases	Avoid inconsistent usage	Google Style Guide - Numbers Read the Google style guide for more information about which form to use for numbers.

Abbreviated terms to spell out

The following terms are important TigerGraph-related concepts that may not be familiar to users outside the TigerGraph community. Spell out each of these terms when they first appear in an article.

• DDL - Data Definition Language

• DML - Data Manipulation Language

• GPE - Graph Processing Engine

• GSE - Graph Storage Engine