Page titles are used in search results and also used to structure the page hierarchy in the breadcrumb list at the top of the page. The page title (which is displayed at the top of the page and in the search results) can be different from the page “slug”, which is the portion of the page’s URL following “/docs/”.
Title and heading capitalization
Page titles and section headings should use headline-style capitalization rather than sentence-style capitalization:
Choosing titles and slugs
Page slugs should be kept short; when creating a new level of hierarchy, the new level’s component in the slug should just be a word or two.
Page titles, on the other hand, may be as long as you like, within reason, and they should be descriptive.
Overly-short articles are hard to find
If an article is “thin”—that is, too short—it may not be indexed properly (or at all) by search engines. As a rule of thumb, the article’s body text should be at least 250-300 words. Don’t artificially inflate a page that can’t reasonably be expanded, but treat this guideline as a minimum target length when possible.
Sections, paragraphs, and newlines
Use heading levels in decreasing order, without skipping levels:
H2 is the highest level allowed because H1 is reserved for the page title. If you need more than three or four levels of headers you should consider breaking up the article into several smaller articles with a parent page or article.
The Enter (or Return) key on your keyboard starts a new paragraph. To insert a newline without a space, hold down the Shift key while pressing Enter.
Don’t create single subsections — you don’t subdivide a topic into one. It’s either two subheadings or more, or none at all.
Don’t have bumping heads, which are headings followed immediately by headings. Aside from looking bad, it’s helpful to readers if every heading has at least a brief intro after it to introduce the subsections beneath.
For words with variant spellings, always use their American English spelling. In general, use the first entry at Dictionary.com, unless that entry is listed as a variant spelling or as being primarily used in a non-American form of English; for example, if you look up “behaviour”, you find the phrase “Chiefly British” followed by a link to the American standard form, “behavior”. Do not use variant spellings.
Correct: localize, behavior
Incorrect: localise, behaviour
User interface actions
In task sequences, describe user interface actions using the imperative mood. Identify the user interface element by its label (in bold, to support scanability) and type.
Correct: Click the Edit button.
Incorrect: Click Edit.
Links are a large part of what makes a knowledge base a powerful learning and teaching tool. We encourage you to create appropriate links among articles; they help improve navigation and discoverability of content, and they provide important context to search engines like Google to help them provide better results.
Every page should have a good set of links from words or phrases to other pages that expand upon the relevant ideas. This can be used both to define terms and to provide more in-depth or detailed documentation about a topic, or to connect to a related page that offers examples or information that may be of further interest.
You can easily create links not only among pages on the Knowledge Base (internal links) but also to pages outside of the Knowledge Base (external links).
There are two ways to create links:
- Explicitly creating a link using the Link button in the “Visual” editor’s toolbar
- Adding the link manually in HTML through the “Text” editor.
When deciding what text to use as a link, there are a few guidelines you can follow:
- For an API name, use the entire string of the API term as written in your content.
- For a term for which you’re linking to a page defining or discussing that term, use the name of the term and no additional text as the link’s text. For example:
- Otherwise, when adding a useful link to prose, try to choose an action and object phrase, such as:
Links to external sites should open in a new browser tab/window. To set a link to open in a new browser tab/window, do the following:
- Click the hyperlinked text.
- Click the Edit button (pencil).
- Click the Link options button (gear).
- Check the Open link in a new tab checkbox (underneath the Link Text field).
For security reasons, you should only create links that use the following schemes:
Others may or may not work, but are not supported and may be removed by editorial staff.
Article tags are an important way to put visitors in touch with helpful content. Each article or post should normally have several tags to help keep content organized. This section explains the best way to tag articles so that our readers can find information and we can keep ourselves organized.
We use a controlled vocabulary but also allow author-contributed tags that are relevant to a specific article. However, we want to avoid creating tags that may only have 1 or 2 articles associated with them when possible.
- Use all lowercase
- No more than two words
- Avoid plural but, if necessary, keep it consistent