Style Guide

All help docs follow the same style and formatting guidelines to make scanning through docs easier. The formatting and style guidelines affect both the metadata and the content of a help doc. For more information on the formatting rules for each section check out the sections below.

Metadata

Help doc metadata refers to additional data that includes important information about the doc. There are both required and required metadata fields that help docs may include that facilitate doc identification, searching, and organization. Check out the list of metadata fields below with their significance.

Required Fields

  • Title - The unique title for a help doc.
  • Section Id - The help doc's primary section.
  • Tag Ids - A list of tags that represents a help doc's required technologies.
  • Created At - The date that the help doc was created.

Optional Fields

  • Updated At - The date that the help doc was last updated.

Help Doc Content

The help doc content refers to the user facing help doc information. While help docs can vary significantly in their content, the following layout guidelines will be enforced for all help docs to maintain consistency and simplify document scanning.

Help Doc Headers

As the help doc title is placed in the document metadata titles will not be used in the document itself. This also means help docs do not support markdown Level 1 or 2 Headings as all doc headers have lower importance than the post title.

Help Docs Code Comments

Comments are included sparingly in help doc code blocks as they tend to clutter up the code example. However, they will be allowed in cases where further information on the code example is required and not directly relevant to the help doc purpose. For help doc relevant code comments, the comment will be extracted into its own section above the code block.

Help Docs Notes

Help doc notes are a catch-all for relevant help doc information that does not belong to a particular section. The Notes section should be kept brief, where large note sections will be a potential indicator that the help doc is too expansive and should be split into multiple docs.

Help Docs Links

Help doc links are external links for any relevant information that may be helpful for understanding the content of the help doc. The link section may be quite extensive and can include links to api documentation, blog posts, stackoverflow questions, etc. All links will include a line that explains the content of the link and its relationship to the help doc.