Docs Writer

docs-writer skill instructions

For ArkEnv register (what/why/how, Turbo-shaped docs, house terms), follow the-voice. This skill is mechanics: links, wrapping, structure. Ignore Gemini CLI naming. When tone and this file conflict, the-voice wins. Site notes use fumadocs <Callout>, not GitHub alerts.

As an expert technical writer and editor, you produce accurate, clear, and consistent documentation. When asked to write, edit, or review documentation, you must ensure the content strictly adheres to the provided documentation standards and accurately reflects the current codebase. Adhere to the contribution process in CONTRIBUTING.md and the following project standards.

Phase 1: Documentation standards

Adhering to these principles and standards when writing, editing, and reviewing.

Voice and tone

Adopt a tone that balances professionalism with a helpful, conversational approach.

• Perspective and tense: Address the reader as "you." Use active voice and present tense (e.g., "The API returns...").
• Tone: Professional, friendly, and direct.
• Clarity: Use simple vocabulary. Avoid jargon, slang, and marketing hype.
• Global Audience: Write in standard US English. Avoid idioms and cultural references.
• Requirements: Be clear about requirements ("must") vs. recommendations ("we recommend"). Avoid "should."
• Word Choice: Avoid "please" and anthropomorphism (e.g., "the server thinks"). Use contractions (don't, it's).

Language and grammar

Write precisely to ensure your instructions are unambiguous.

• Abbreviations: Avoid Latin abbreviations; use "for example" (not "e.g.") and "that is" (not "i.e.").
• Punctuation: Use the serial comma. Place periods and commas inside quotation marks.
• Dates: Use unambiguous formats (e.g., "January 22, 2026").
• Conciseness: Use "lets you" instead of "allows you to." Use precise, specific verbs.
• Examples: Use meaningful names in examples; avoid placeholders like "foo" or "bar."
• Quota and limit terminology: For any content involving resource capacity or using the word "quota" or "limit", strictly adhere to the guidelines in the quota-limit-style-guide.md resource file. Generally, Use "quota" for the administrative bucket and "limit" for the numerical ceiling.

Formatting and syntax

Apply consistent formatting to make documentation visually organized and accessible.

• Overview paragraphs: Every heading must be followed by at least one introductory overview paragraph before any lists or sub-headings.

• Text wrap: Wrap text at 80 characters (except long links or tables).

• Casing: Use sentence case for headings, titles, and bolded text.

• Naming: Always refer to the project as ArkEnv (never the ArkEnv).

• Lists: Use numbered lists for sequential steps and bulleted lists otherwise. Keep list items parallel in structure.

• UI and code: Use bold for UI elements and code font for filenames, snippets, commands, and API elements. Focus on the task when discussing interaction.

• Accessibility: Use semantic HTML elements correctly (headings, lists, tables).

• Media: Use lowercase hyphenated filenames. Provide descriptive alt text for all images.

• Details section: Use the <details> tag to create a collapsible section. This is useful for supplementary or data-heavy information that isn't critical to the main flow.

  Example:

  <details>
  <summary>Title</summary>

  • First entry
  • Second entry

  </details>

• Callouts: Use GitHub-flavored markdown alerts to highlight important information. To ensure the formatting is preserved by npm run format, place an empty line, then a prettier ignore comment directly before the callout block. Use <!-- prettier-ignore --> for standard Markdown files (.md) and {/* prettier-ignore */} for MDX files (.mdx). The callout type ([!TYPE]) should be on the first line, followed by a newline, and then the content, with each subsequent line of content starting with >. Available types are NOTE, TIP, IMPORTANT, WARNING, and CAUTION.

  Example (.md):

<!-- prettier-ignore -->

[!NOTE] This is an example of a multi-line note that will be preserved by Prettier.

Example (.mdx):

{/* prettier-ignore */}

[!NOTE] This is an example of a multi-line note that will be preserved by Prettier.

Links

• Accessibility: Use descriptive anchor text; avoid "click here." Ensure the link makes sense out of context, such as when being read by a screen reader.
• Use relative links in docs: Use relative links in documentation (/docs/) to ensure portability. Use paths relative to the current file's directory (for example, ../tools/ from docs/cli/). Do not include the /docs/ section of a path, but do verify that the resulting relative link exists. This does not apply to meta files such as README.MD and CONTRIBUTING.MD.
• When changing headings, check for deep links: If a user is changing a heading, check for deep links to that heading in other pages and update accordingly.