Thank you for your interest in contributing to our documentation. We put together this guide to help you get started, whether you want to fix minor spelling/grammar issues or have a more ambitious goal to write a new article.
There are two types of documentation; articles and API references. Articles are documents that use GitHub-flavored Markdown syntax located in our packages. API references include details such as classes and methods and are located within the code they describe.
Each article begins with a YAML metadata block followed by a body written with GitHub-flavored Markdown syntax. The YAML metadata block provides key information needed by our documentation system. Here's an example of this document's YAML metadata block:
The required fields are:
- id: A human-readable unique ID used in the document URL.
- title: The title displayed at the top of the document.
- sidebar_label: The label displayed in the table of contents.
- custom_edit_url: A URL where the document source can be edited.
Beneath the YAML metadata block, article's body is written with GitHub-flavored Markdown syntax. Since our documentation system will turn the
title metadata into the article header, the content should begin with a short introductory paragraph, followed by an h2 header for each section of the document. You may use h3 headers beneath h2 headers but avoid deeper sub-sections.
In addition to GitHub-flavored Markdown syntax, you may use the admonitions
warning. Here's an example of the syntax for a
Which is rendered as:
This is a note
Writing API references
An API reference is written inline with code using TSDoc syntax. TSDoc is a proposal to standardize documentation comments used in TypeScript source files. It allows tools to extract content from comments without getting confused by differing syntax. The TSDoc notation should be familiar:
Building and testing the docs
To test documentation changes, clone and build the documentation as described in the contributor guide. Next, open a terminal and navigate to
sites/website and run the documentation site with
yarn dev to preview the site and validate your changes are rendering.
Writing guidelines for this project come from the Chicago Manual of Style and The Associated Press Stylebook. If these two publications have conflicting guidance, the Chicago Manual of Style guidance is preferred.
We recognize that our contributors may not have access to these resources, so we provide a style guide amendment that covers common issues and guidance specific to this project, or guidance that is not specified in other guides.
For guidance not specified by this amendment, several free resources can be used as a supplement:
Style guide amendment
Parentheses with periods: When a complete sentence is inside of parentheses, place the period inside the ending parenthesis. If the words are not a complete sentence the period or other punctuation goes on the outside.
A complete sentence in parenthesis:
(The first time it said 'hello world,' I knew we would be friends.)
A sentence fragment in parenthesis:
The first time it said 'hello world,' I knew we would be friends (and we still are).
Quotation marks with periods: When a sentence ends with a quotation mark, the period goes on the inside. The only exception to this rule in cases where the quotation marks are around text intended to be input by the user, but in these cases, use
The boy said, "The first time it said 'hello world,' I knew we would be friends." At the prompt, type
Colons on sentences: When a sentence proceeds and is describing or introducing a code block, list or example; use a colon.
To run the script, type:run hello-world
It has said the following:
- hello world
An example of how to format phrases it can say:
Hello world Hello world! Hello world?
Periods on sentences: Except for a sentence proceeding a code block, list, or example; end all complete sentences with a period including sentences in code comments and list items.
// Update this string to change what it will say.alert("hello world");
Over the years, I have had a few computers say 'hello world' to me:
- The first was a CBM 8032 I received for my 12th birthday.
Sentence case headings: Headings formatted in sentence case. The exception is proper names and acronyms that are capitalized.
Heading in sentence case:
My first computer
Heading with acronym:
My first CBM 8032
Heading with proper name:
My first Commodore
Punctuation on headings: Do not put periods on headings and avoid headings that are questions or complete sentences.
HTML elements: When referencing HTML elements, use the element syntax inside angle brackets with the word 'element' or 'elements' in context. Include a link to the MDN documentation for the element:
<a>element for hypertext.
UI text: When referencing text in a UI such as a name in a button or menu item, use bold formatting:
Click the submit button.
Named objects: When referencing named objects such as other components or packages, use italic formatting with a descriptive word such as "component" in context:
Use the button component.
Code: When referencing code, console commands, or file names; use
npm startin the console.
console.log()method outputs a message to the console.
Element spacing: Use one line break between markdown elements.
For example, between headings, paragraphs, code fences, and images:
Trailing space: Remove trailing spaces at the end of elements. Include one new line character at the end of the markdown file.
Unordered lists: Use
* syntax for un-ordered lists:
Technologies used:* TypeScript* React* JSS
Code fence languages: Provide a language for code fences:
Example CSS code fence:
You can find a list of supported languages here.
Testing examples: Test your code examples to verify they work.
Code guidelines: Verify that code examples follow the project's coding guidelines. For example, four spaces for indenting.
Code comments can be fragments or complete sentences. Depending on the format, there are slightly different guidelines.
Code comments in sentence format:
- Can be formatted as a single line or multi-line syntax.
- Have a period or question mark at the end.
Code comments in fragment format:
- Are formatted as single-line syntax.
- Do not have period or question mark at the end.