Standards for written content in [#technical-documentation]

LinkORB has the following requirements for all technical documents:

Brand and styling consistency

• In technical documents LinkORB is written as “LinkORB” as opposed to “linkorb”.
• The LinkORB logo orange is RGB(255,128,0) and Hex #FF8000.
• For a dark contrasting color, both black and RGB(32, 16, 0) and Hex #201000 are useful and approved.
• Two shades of light-gray RGB(240, 238, 237) and Hex #F0EEED and RGB(255, 255, 255) and Hex #FFFFFF are also commonly used.
• Preference should be given to LinkORB brand colors in all custom visuals, screenshot markings, and similar artifacts.

Documentation location

When adding longer, specialized documentation to a project repository, use a dedicated file in the docs/ directory at the project root. Please create the docs/ directory if it does not already exist.

Brief and introductory content related to the build, run, test, and other similar commands of a project repository can be stored in the repository’s README.md file.

Save internal documents to the internal wiki or discuss an appropriate location with your team lead and appropriate team members before publishing the document.

File naming convention

File names should be kept short, ideally containing 1 to 2 words (3 maximum). Additionally, file names should not contain whitespace. Hyphens - should be used between words.

These file naming standards assist with keeping URLs short and readable.

.MD versus .MDX file formats

In most cases, .md format is preferred to .mdx. In applications that support .mdx, it should only be used when required. Reasons for this preference include:

• Support reuse or migration of content across applications that may not support .mdx
• Not all application tooling such as search indexing, automated table of contents, and Markdown linting support .mdx.

Use of Markdown and pull requests

At LinkORB “documentation is code”. As such, most production technical documentation is written in Markdown and becomes a pull request against a repository or the LinkORB Engineering site.

See Create a pull request for more information.

Provide an overview

At the beginning of a guide, describe its purpose. For example, is the guide’s goal to explain something (informational) or to teach you how to do something (instructional)?

For example:

• This [insert guide name] guide provides an overview of…
• This [insert guide name] guide shows how to…

If a guide is specific to a code repository, such as one of LinkORB’s open-source projects, provide the project’s:

• purpose
• features
• use

An example of a guide with a clearly stated purpose is Your first day and week at linkorb guide.

You can also provide a diagram that shows how the system fits into the larger picture. However, it’s important to follow LinkORB’s standards for adding custom visuals as described in Embedding custom visuals guide.

For example, an overview of the Herald open-source project would be:

Herald is an open-source, transactional email API service that any application can use for email templating, sending, queueing, and debugging.

Using table of contents

All documents over two pages should have a table of contents (TOC) located immediately after the document overview.

The TOC should be automatically generated based on Markdown, please see this article for suggestions on automating the TOC.

State the intended audience (when needed)

Especially if a repository is public, add an Intended audience section that describes who would use the guide. It may not be necessary to state the intended audience for a guide if it is internal only and provides general guidelines/standards.

For example:

• Does the guide cover an internal or public code repository or GUI? Or is it both internal and public?
• Are the users just developers, or does it include operations, testers, technical writers, and business stakeholders?

List prerequisites

Document the knowledge and tools required to use the guide in a Prerequisites section.

Ask yourself:

• Do they need to create an account?
• What tools do they need to install to follow the guide?
• Do they need a certain degree of knowledge of the subject, or is the guide beginner-level?
• What guides do we assume they have read that we have written?

Document uncommon information

LinkORB users have a certain level of technical competency. For example, there is no need to describe common UI elements and labels, such as:

• name
• description
• comment
• password
• date
• default value
• data type
• file upload
• back button
• save button

Instead, focus on the essential things in the document that could be unfamiliar, such as fields and values whose meaning is not apparent based on their name. For example, you may need to choose from a list of enums with strange names like ROLE_USERGROUP: SCHEMATA-TEAM.

Header size

Only use H2 (##) to H6 (######) headers in a Markdown document. See Only use H2 to H6 headers in Markdown documents for more information.

Header length

Header length should be kept short to minimize wrapping.

Header capitalization

In headers, only the first word and proper names are capitalized.

For example “Header capitalization for writers at LinkORB” is preferred to “Header Capitalization for Writers at LinkORB”.

Use of acronyms

Writers should avoid unnecessary use of acronyms. However when used, spell out the acronym in full before first use.

Example: Please don’t laugh out loud (LOL) at my use of acronyms.

There is one exception to the above. When an acronym’s first use occurs in a header, fully spell out the acronym but do not provide the acronym itself in the header. Only provide the acronym following the fully spelled acronym’s first use in a paragraph.

The reason for this rule is to shorten header length and omit parenthesis from headers.

Once the acronym has been defined in a paragraph, it can be used alone in subsequent headers in the same document.

Apply custom styling to Markdown on a single page

If a block of Markdown content requires custom styles, do the following:

1. Wrap the block of Markdown in HTML (container) tags such as <div></div> and assign a class name to that tag.
2. Add an empty line immediately before and after the Markdown block inside the HTML wrapper tags.
3. Add <style></style> tags directly above the wrapper element (div) and define custom styles that target the wrapper’s descendants.

For example, the following overrides the site’s default table style by defining a CSS class custom-table-wrapper where the contents of the first column are bold and the contents of third column are prevented from wrapping to a new line.

<style>
  .custom-table-wrapper td:nth-child(1) {
    font-weight: bold;
  }

  .custom-table-wrapper td:nth-child(3) {
    width: fit-content;
    white-space: nowrap;
  }
</style>

<div class="custom-table-wrapper">

| Type | Description | Example |
| --- | --- | --- |
| feat | Non-breaking change which adds new functionality | feat: auto refresh messages #1024 |
| fix | Non-breaking change which fixes a bug or an issue | fix: expired token loop #2048 |

</div>

The above example will render as shown below:

When custom styles are intended for use on a single page, embedding them at the point of use instead of the global style sheet, reduces chances of name collisions.

Prefer directives to HTML

Use remark directive to embed HTML elements that do not have Markdown counterparts. Please see the Directives and custom UI elements guide for how to embed directives in Markdown documents.

Writing effective lists

An effective list must be of the appropriate type and its items should be parallel.

List types

Choose an appropriate list type. Your list can be:

• numbered (ordered)
• bulleted (unordered)
• collapsible (quick reads)

Numbered (ordered)

Use a numbered list when describing a multi-step task, in which one step must come before the other. To determine if you need a numbered list, consider whether the list’s overall meaning changes when you rearrange its items. If your answer is yes, use a numbered (ordered) list. For example, the following list will lose its meaning if rearranged:

1. Click the Code button.
2. Click the Codespaces tab.
3. Click the Create Codespace on main button.

Bulleted (Unordered)

Use a bulleted list if the meaning of the overall list does not change when the items are rearranged.

Collapsible lists

Use collapsible lists to present F.A.Q-style content that allows readers to skim and only engage with relevant topics without scrolling (too much 👨‍💻).

Use collapsible lists to present F.A.Q-style content that allows readers to skim and only engage with relevant topics without scrolling (too much 👨‍💻). See the collapsible lists section of the Directives and custom UI elements guide for more information.

Write parallel list items

The items in an effective list are parallel. That is, they are consistent in terms of:

• capitalization
• punctuation
• grammar (singular, plural, tenses, etc.)

The list above is mixed because the grammar item gives examples and uses punctuation when other items do not. A better strategy is to re-write the list items to be parallel and then write additional information about each item in a separate section as follows:

• capitalization
• punctuation
• grammar

Capitalization

Capitalize a list item like you would a sentence, only if the item is a complete sentence. Having capitalized one item in a list, do the same for other items to maintain consistency. If the items in a list are not complete sentences, write them in all-lowercase characters.

Punctuation

Punctuate a list item like you would a sentence, only if it is a complete sentence. Similar to the capitalization rule, you would have to punctuate other items in the list to ensure consistency.

Grammar

Ensure uniform use of tenses, numbers, and other properties in each list item.

If you encounter such lists, write the list items exactly how they are written on other platforms. For example, the following list does not pass the capitalization and punctuation check, but it is consistent.

• LinkORB
• WhatsApp
• Yahoo!
• YouTube

Reference source documentation

Unless LinkORB’s use case differs significantly from source documentation, please refer readers to source material (READMEs, guides, blogs, or videos) when referencing applications and tools that have their own existing documentation.

Avoid internal references

With screenshots and content, use an open-source approach. Do not post or reference specific internal projects, team member names, or LinkORB-only concepts. Use globally familiar concepts or provide generalized examples supporting the topic of focus.