diff --git a/.github/instructions/writing-style.instructions.md b/.github/instructions/writing-style.instructions.md new file mode 100644 index 00000000..e3824586 --- /dev/null +++ b/.github/instructions/writing-style.instructions.md @@ -0,0 +1,145 @@ +--- +applyTo: '**/*.md,**/*.mdx' +--- + +# Writing and markdown instructions for documentation + +## Audience + +The primary audience for this documentation is developers and DevOps +professionals who want to run and manage Model Context Protocol (MCP) servers +using ToolHive. They may be new to MCP servers or have some experience with +them. + +The documentation should be accessible to a wide range of technical users, +including those who may not be familiar with the specific technologies used in +ToolHive. + +## Language, tone, and voice + +- The project's official language is US English. + +### Tone and voice + +- Strive for a casual and conversational tone without becoming overly informal. +- Be friendly and relatable while retaining credibility and professionalism. +- Avoid slang and colloquial expressions. +- Use clear, straightforward language and avoid overly complex jargon to make + content accessible to a wide audience. +- Use active voice instead of passive voice. +- Address the reader using the second person ("you", "your"). Avoid the first + person ("we", "our") and third person ("the user", "a developer"). + +### Capitalization + +- Capitalize proper nouns like names, companies, and products. Generally, don't + capitalize features or generic terms. +- Use sentence case in titles and headings. +- Use `ALL_CAPS` to indicate placeholder text/parameters, where the reader is + expected to change a value. +- Expand acronyms on first use, then use the acronym in subsequent references. + - Exception: MCP is used ubiquitously in this project, so it does not need to + be expanded on first use. + +### Punctuation + +- Use the Oxford comma (aka serial commas) when listing items in a series. +- Use one space between sentences. +- Use straight double quotes and apostrophes. Replace smart quotes (“ ”) and + curly apostrophes (’ ’) with straight quotes (") and straight apostrophes ('). + +### Links + +- Use descriptive link text. Besides providing clear context to the reader, this + improves accessibility for screen readers. +- When referencing other docs/headings by title, use sentence case so the + reference matches the corresponding title or heading. + +### Images + +- Use images sparingly and only when they add value to the content. +- Use images to illustrate complex concepts, provide examples, or enhance + understanding. +- Use screenshots to show UI elements or workflows, but ensure they are clear, + relevant, and add value to the content. +- Don't use images of text, code samples, or terminal output. Use actual text so + readers can copy/paste and find the contents via search engines. +- Add alt text to images to describe their content and purpose. This improves + accessibility for users with visual impairments. + +### Examples + +- Use examples to clarify complex concepts or demonstrate how to use a feature. +- Prefer practical, real-world examples over abstract or contrived ones. + +### Formatting + +- Bold: use when referring to UI elements; prefer bold over quotes. +- Italics: emphasize particular words or phrases, such as when + introducing/defining a term. +- Underscore: do not use; reserved for links. +- Use inline code formatting for short code elements, such as variable names, + function names, or command-line options. +- Use block code formatting for longer code snippets or examples. + +### Word list + +Common terms used in this project: + +- ToolHive - this project, an open source tool that helps you run and manage MCP + servers easily and securely +- Stacklok - the company behind ToolHive +- GitHub Copilot +- Model Context Protocol (MCP) +- open source (not "open-source") +- large language model (LLM) +- Visual Studio Code ("VS Code" after first use) + +Check this list for consistent use within the documentation. If you find +inconsistencies, update the text to match the preferred term. If you find a term +that is not listed here, consider adding it to the list for future reference. + +## Markdown style + +Prettier and markdownlint are used to enforce the following Markdown style +conventions. + +- Headings: use "ATX-style" headings +- Use unique headings within a document +- Unordered lists: use hyphens (`-`), not asterisks (`*`) +- Bold: Use the `**` syntax for bold text, not `__` +- Italics: Use the `__` syntax for italic text, not `*` +- Ordered lists: use lazy numbering for long or verbose lists. + - Note: this is a "soft" recommendation. It is also intended only for Markdown + documents that are read through a rendering engine. If the Markdown will be + consumed in raw form like a repo README file, use real numbering. +- Code blocks: use fenced code blocks (` ``` ` to begin/end) and always declare + the language. If the language is unknown or plain text like log output, use + `text` as the language. +- Add blank lines around headings, lists, and code blocks. +- No trailing whitespace on lines. + - Use the `\` character at the end of a line for a single-line break, not the + two-space syntax which is easy to miss. Exception: +- Line limit: wrap lines at 80 characters; exceptions for links, tables, + headings, and code blocks + +### Docusaurus specifics + +This website is built using Docusaurus, which has some specific requirements and +conventions for Markdown files: + +- Heading 1 is reserved for the page title, typically defined in the Markdown + front matter section. Sections within a page begin with Heading 2 (`##`). +- Use relative file links (with .md/.mdx extensions) when referring to other + pages. +- Use the .mdx extension for pages containing JSX includes. +- Use the front matter section on all pages. At a minimum, set the `title` (this + is rendered into the page as an H1) and a short `description`. +- Use the `admonition` component for notes, tips, warnings, and other + annotations. This provides a consistent look and feel across the site. + - Use the `:::type` syntax to define the admonition type, such as `note`, + `tip`, `info`, `warning`, or `danger`. +- Place images in `static/img` using WebP, PNG, or SVG format. +- Use the `ThemedImage` component to provide both light and dark mode + screenshots for apps/UIs that support both. +- Use the `Tabs` and `TabItem` components to create tabbed content sections.