Skip to main content

Documentation Style Guide

Purpose

This comprehensive style guide ensures consistency across all Mind Your Now documentation. Follow these guidelines to create professional, user-friendly documentation that aligns with our brand and user experience goals.

Writing Style & Voice​

Brand Voice​

Mind Your Now documentation should be:

  • Conversational: Write like you're helping a friend
  • Clear & Concise: Get to the point without unnecessary complexity
  • Encouraging: Focus on empowering users to succeed
  • Professional: Maintain expertise while being approachable
  • Inclusive: Use language that welcomes all users

Tone Guidelines​

Do Use​

  • Active voice: "Click the Save button" (not "The Save button should be clicked")
  • Second person: "You can organize your tasks by..."
  • Present tense: "Mind Your Now helps you..." (not "Mind Your Now will help...")
  • Positive language: "To enable this feature..." (not "To turn off this limitation...")

Avoid​

  • Jargon without explanation
  • Overly technical language
  • Negative constructions when positive alternatives exist
  • Assumptions about user knowledge level

Content Structure & Organization​

Document Hierarchy​

Page Structure​

# Primary Title (H1) - Only one per page
## Major Sections (H2) - Main content divisions
### Subsections (H3) - Detailed breakdowns
#### Minor Points (H4) - Specific details

Information Architecture​

  1. Overview: What this feature/topic is about
  2. Benefits: Why users should care
  3. Getting Started: How to begin using it
  4. Detailed Instructions: Step-by-step guidance
  5. Advanced Usage: Power user features
  6. Troubleshooting: Common issues and solutions
  7. Related Topics: What to explore next

Content Types & Templates​

Feature Documentation​

  • Use Feature Overview Template for introducing new capabilities
  • Use User Guide Template for comprehensive how-to information
  • Use Quick Reference Template for at-a-glance information

Process Documentation​

  • Use numbered steps for sequential processes
  • Use bullet points for non-sequential lists
  • Include expected outcomes for each major step

Writing Guidelines​

Headers & Titles​

Capitalization​

  • Use sentence case for all headers: "Managing your household chores"
  • Capitalize proper nouns: "Google Calendar integration"
  • Be descriptive but concise

Naming Conventions​

  • Feature names: Use official product terminology consistently
  • UI elements: Match exactly what appears in the interface
  • Actions: Use active verbs ("Create a new habit" not "New habit creation")

Lists & Formatting​

Bullet Points​

  • Use parallel structure (all items should have similar grammatical form)
  • Keep items concise but complete
  • Use sub-bullets sparingly (maximum 2 levels)

Numbered Lists​

  • Use for sequential steps or processes
  • Start each item with an action verb when appropriate
  • Include expected results when helpful

Formatting Standards​

  • Bold: For UI elements, important terms, and emphasis
  • Italic: For first use of technical terms or subtle emphasis
  • Code font: For exact text users will see, buttons, or field names

  • Blockquotes: For important callouts or user quotes

Links & Cross-References​

  • Link to relevant sections within documents
  • Use descriptive link text: "see the Calendar Integration guide"
  • Avoid "click here" or generic phrases
  • Open in new tabs/windows for external sites
  • Provide context for what users will find
  • Keep external links current and relevant

Visual Elements​

Screenshots & Images​

When to Include​

  • New or complex UI elements
  • Multi-step processes that benefit from visual guidance
  • Before/after states to show results
  • Mobile vs. desktop differences

Image Guidelines​

  • Follow Screenshot Annotation Standards
  • Include descriptive alt text for accessibility
  • Use consistent annotation styles and colors
  • Optimize file sizes for web performance

Captions & Alt Text​

  • Captions: Explain what the image shows and why it's relevant
  • Alt Text: Describe the image content for screen readers
  • Be specific but concise

Tables​

When to Use Tables​

  • Comparing features or options
  • Reference information (shortcuts, settings, etc.)
  • Structured data that benefits from columns

Table Guidelines​

  • Keep tables simple and scannable
  • Use header rows for column identification
  • Avoid overly wide tables that require horizontal scrolling
  • Consider responsive design for mobile users

Code Examples​

Formatting​

Use fenced code blocks for multi-line examples:

Your code here


Use `inline code` for short references or UI text.

Best Practices​

  • Include comments explaining complex parts
  • Show realistic examples, not just syntax
  • Provide context for when to use each example

Content Guidelines​

User-Focused Writing​

Lead with Benefits​

  • Start with what users can accomplish
  • Explain the "why" before the "how"
  • Connect features to real user goals

Assume Positive Intent​

  • Users want to learn and succeed
  • Provide helpful guidance, not warnings about mistakes
  • Frame limitations as current capabilities

Accessibility​

Language Accessibility​

  • Use plain language whenever possible
  • Define technical terms when first introduced
  • Provide multiple ways to understand concepts (text, visuals, examples)

Technical Accessibility​

  • Include alt text for all images
  • Use proper heading hierarchy
  • Ensure sufficient color contrast in custom elements
  • Test with screen readers when possible

Internationalization Considerations​

Writing for Translation​

  • Use clear, complete sentences
  • Avoid idioms and culturally specific references
  • Keep UI text consistent with the actual interface
  • Consider text expansion in other languages

MDX & Component Usage​

Docusaurus Components​

Admonitions​

Use built-in admonitions for different types of information:

:::tip[Pro Tip]
Use this for helpful suggestions and best practices.
:::

:::info[Good to Know]
Use this for additional context or background information.
:::

:::warning[Important]
Use this for important information users shouldn't miss.
:::

:::danger[Critical]
Use this sparingly for critical warnings or data loss scenarios.
:::

Custom Components​

  • Use our custom components from src/components/docs/
  • FeatureHighlight: For showcasing key capabilities
  • ComparisonTable: For before/after or feature comparisons
  • StepByStep: For guided processes with optional images

Component Guidelines​

When to Use Custom Components​

  • Complex layouts that improve user understanding
  • Repeated patterns across multiple documents
  • Interactive elements that enhance the experience

Consistency Rules​

  • Use the same component for similar content types
  • Follow established patterns for component props
  • Test components across different content scenarios

Quality Standards​

Content Review Checklist​

Before Publishing​

  • Content follows the established template structure
  • All screenshots are clear and properly annotated
  • Links work and point to current information
  • Code examples are tested and functional
  • Language is clear and user-friendly
  • Headers follow proper hierarchy
  • Images have descriptive alt text
  • Content serves a clear user need

Editorial Review​

  • Grammar and spelling are correct
  • Terminology is consistent across documents
  • Tone matches brand voice guidelines
  • Content is appropriately detailed for the audience
  • Cross-references are accurate and helpful

Technical Review​

  • Instructions are accurate and complete
  • Screenshots match current UI
  • Code examples work as expected
  • Links are functional and current
  • Mobile experience is considered

Maintenance Standards​

Regular Updates​

  • Review content quarterly for accuracy
  • Update screenshots when UI changes
  • Refresh examples with current best practices
  • Archive or redirect outdated content

Version Control​

  • Use clear commit messages for documentation changes
  • Track major updates in changelog format
  • Coordinate with product releases for feature documentation

Brand & Terminology​

Product Names & Features​

  • Mind Your Now: Always capitalize, never abbreviate to "MYN" in user-facing content
  • Chore Management: Capitalize when referring to the feature
  • Habit Tracking: Capitalize when referring to the feature
  • Achievement System: Capitalize when referring to the feature

UI Terminology​

Match interface text exactly:

  • Button labels: Use exact text from the interface
  • Menu items: Copy precisely from the application
  • Field labels: Match form labels exactly
  • Status messages: Quote interface messages when relevant

Technical Terms​

  • Define technical terms on first use
  • Maintain a glossary for complex products
  • Use consistent terminology throughout all documentation
  • Avoid mixing synonyms for the same concept

SEO & Discoverability​

Page Titles & Headers​

  • Include relevant keywords naturally
  • Make titles descriptive and specific
  • Use headers to structure content for scanning
  • Consider what users might search for

Meta Descriptions​

  • Summarize page content in 150-160 characters
  • Include primary keywords naturally
  • Make it compelling enough to encourage clicks
  • Avoid keyword stuffing

Internal Linking​

  • Link to related content within the site
  • Use descriptive anchor text
  • Create topic clusters around related features
  • Help users discover relevant information

Quick Reference​

Common Patterns​

  • Feature Introduction: Benefits → Overview → Getting Started
  • Process Documentation: Prerequisites → Step-by-step → Verification
  • Troubleshooting: Problem → Cause → Solution → Prevention

Formatting Quick Guide​

  • Emphasis: Use bold for UI elements and important terms
  • Code: Use backticks for button names and exact text
  • Links: Use descriptive text, not "click here"
  • Lists: Parallel structure, action verbs for steps

Review Questions​

  1. Would a new user understand this without additional context?
  2. Does this help users accomplish their goals?
  3. Is the information current and accurate?
  4. Does this follow our established patterns and voice?

This style guide is a living document. Suggest improvements by contacting the documentation team.