Deno Documentation Style Guide

This guide outlines the standards and best practices for writing documentation for Deno. Following these guidelines helps ensure our documentation remains consistent, clear, and helpful for all users.

Document Structure Jump to heading#

Front Matter Jump to heading#

Every Markdown file should begin with front matter that includes:

---
title: "Descriptive Title"
description: "A concise summary (1-2 sentences) of the page content that will appear in search results and link previews."
oldUrl:  # Optional - used for redirects from previous documentation locations
- /previous/url/path/
---

Title: Concise but descriptive, enclosed in quotes.

Description: 1-2 sentences (140-160 characters) that summarize the page content.

Introduction paragraph Jump to heading#

Begin each document with a brief introduction that explains:

• What the feature/concept is
• Why it's useful
• Who might need this information

Content Organization Jump to heading#

Organize content in a logical progression:

1. Basic concepts first
2. Common use cases
3. Advanced features
4. Reference information

Writing Style Jump to heading#

Voice and Tone Jump to heading#

• Be conversational but professional - Write as if you're explaining to a colleague
• Use active voice - "Deno provides..." rather than "...is provided by Deno"
• Be direct - Address the reader as "you"
• Be concise - Use simple sentences and avoid unnecessary words

Technical Writing Conventions Jump to heading#

• Define terms before using them
• Use consistent terminology throughout the documentation
• Avoid idioms and colloquialisms*that may confuse non-native English speakers

Grammar and Mechanics Jump to heading#

• Use American English spelling and conventions
• Write in present tense when possible
• Avoid contractions in formal explanations (use "cannot" instead of "can't")
• Use sentence case for headings (capitalize only the first word and proper nouns)

Code Examples Jump to heading#

Format Jump to heading#

• Always specify the language for syntax highlighting
• For TypeScript/JavaScript, use ts or js language identifiers
• Include file names when appropriate using the title attribute

```ts title="example.ts"
function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("world"));
```

Best Practices for Examples Jump to heading#

• Keep examples simple and focused on demonstrating one concept
• Ensure all examples are functional and correct
• Include comments for complex or non-obvious code sections
• Show both basic and practical use cases
• For longer examples, build them incrementally

Documentation Tests Jump to heading#

For code blocks that should be tested:

• Ensure examples in documentation are correct and runnable
• Use triple backticks with language identifiers to enable testable code blocks
• Follow the guidelines in Documentation Tests

Formatting Elements Jump to heading#

Links Jump to heading#

• Use descriptive link text that makes sense out of context
• For internal links, use relative paths, ending in a /: /runtime/fundamentals/modules/
• Link to relevant documentation when introducing new concepts

[descriptive text](/path/to/page/)

Lists Jump to heading#

• Use ordered lists (1., 2., 3.) for sequential steps
• Use unordered lists (bullet points) for non-sequential items
• Keep list items parallel in structure
• Capitalize the first word of each item

Admonitions (Notes, Tips, Warnings) Jump to heading#

Use admonitions sparingly to highlight important information:

:::note Important supplementary information. :::

:::tip Helpful advice for better usage. :::

:::caution Warn about potential issues or gotchas. :::

Tables Jump to heading#

Use tables for presenting structured data:

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Specific Content Types Jump to heading#

Command Reference Jump to heading#

When documenting CLI commands:

• Begin with a clear description of what the command does
• List all available flags and options
• Include examples showing common usage patterns
• When possible, show expected output

API Documentation Jump to heading#

For API documentation:

• Clearly define parameters and return values
• Specify types for all parameters
• Provide examples for common use cases
• Document potential errors or exceptions

Tutorials Jump to heading#

For tutorial-style documentation:

• Begin with prerequisites and what will be learned
• Break down into clear, numbered steps
• Provide complete code examples
• Explain the "why" behind each step, not just the "how"
• End with next steps or related resources

Visual Elements Jump to heading#

Screenshots and Images Jump to heading#

• Include alt text for all images
• Keep images up to date with the current UI
• Crop images to focus on relevant parts
• Use annotations to highlight important areas
• Ensure images are clear at different screen sizes

Diagrams Jump to heading#

• Use diagrams to explain complex concepts or flows
• Keep diagrams simple and focused on the key message
• Include text explanations that complement the diagram

Inclusive Language Jump to heading#

• Use gender-neutral language
• Avoid terminology with problematic historical connotations
• Be mindful of global audiences and avoid culture-specific references
• Follow the inclusive code guidelines

Review Process Jump to heading#

Before submitting documentation:

1. Verify technical accuracy
2. Check for clarity and readability
3. Ensure consistent formatting
4. Validate all links
5. Test all code examples
6. Review for typos and grammatical errors

File Organization Jump to heading#

• Place new files in the appropriate directory based on content type
• Use lowercase for filenames with words separated by underscores (e.g., setup_environment.md)
• Follow the existing navigation structure when adding new pages