Skip to main content

Documentation Guidelines

This document provides conventions and best practices for writing and maintaining documentation in the ProvLabs documentation website.

Markdown Standards​

File Organization​

  • Documentation files are stored in the docs/ directory
  • Use descriptive filenames with .md extension
  • Organize content in logical subdirectories (e.g., learn/, build/)
  • Follow Docusaurus file naming conventions for proper routing

Markdown Linting​

  • All markdown files must pass markdownlint-cli validation
  • Configuration is defined in .markdownlint.json
  • Use asterisk style for unordered lists (MD004)
  • 4-space indentation for nested lists (MD007)
  • Line length restrictions are disabled (MD013: false)

Content Structure​

Document Headers​

# Main Title

Brief description of the document's purpose and scope.

## Section Headers

Use proper heading hierarchy (H1 → H2 → H3 → H4)

Code Examples​

  • Use fenced code blocks with language specification
  • Provide complete, runnable examples when possible
  • Include comments explaining complex operations
# Example script execution
npm run build

Docusaurus Integration​

  • Sidebar structure is defined in sidebar.ts
  • Use descriptive labels for navigation items
  • Group related documentation logically
  • Maintain consistent naming patterns

Front Matter​

---
title: Document Title
description: Brief description for SEO
sidebar_label: Navigation Label
---

Cross-References​

  • Use relative paths for internal links
  • Reference other documentation files using Docusaurus link syntax
  • Maintain link integrity during file reorganization

API Documentation​

OpenAPI Integration​

  • API documentation is generated from OpenAPI specifications
  • Do not manually edit generated API docs
  • Provide supplementary documentation for complex workflows
  • Link to relevant API sections from conceptual documentation

Code Snippets​

  • Include practical examples for API usage
  • Show both request and response examples
  • Cover common error scenarios and handling

Style Guidelines​

Writing Style​

  • Write in clear, concise language
  • Use active voice when possible
  • Define technical terms on first use
  • Maintain consistency in terminology throughout documentation

Formatting​

  • Use consistent formatting for:
    • Command line examples
    • File paths
    • API endpoints
    • Configuration parameters
  • Emphasize important information with callouts or highlighted text

Content Types​

Getting Started Guides​

  • Provide step-by-step instructions
  • Include prerequisites and setup requirements
  • Test all instructions on a clean environment
  • Anticipate common issues and provide solutions

Reference Documentation​

  • Organize information logically (alphabetically or by function)
  • Provide complete parameter lists and descriptions
  • Include examples for each major feature
  • Link to related concepts and tutorials

Troubleshooting Guides​

  • Start with most common issues
  • Provide diagnostic steps
  • Include multiple solution approaches when applicable
  • Reference logs and error messages specifically

Asset Management​

Images and Media​

  • Store images in static/img/ directory
  • Use descriptive filenames for images
  • Optimize images for web delivery
  • Provide alt text for accessibility
  • Use consistent image sizing and formatting
  • Verify external links regularly
  • Use HTTPS links when available
  • Consider link permanence for critical references
  • Provide context for external resources

Review Process​

Quality Checklist​

  • Content is accurate and up-to-date
  • All links work correctly
  • Code examples have been tested
  • Markdown linting passes
  • Spelling and grammar are correct
  • Information is organized logically

Maintenance​

  • Review documentation quarterly for accuracy
  • Update examples when APIs change
  • Remove or update deprecated information
  • Maintain consistency with current product features

Accessibility​

Writing for Accessibility​

  • Use descriptive link text (avoid "click here")
  • Structure content with proper headings
  • Provide alternative text for images
  • Use sufficient color contrast in diagrams
  • Test with screen readers when possible

Inclusive Language​

  • Use inclusive and welcoming language
  • Avoid unnecessarily complex technical jargon
  • Define acronyms and abbreviations
  • Consider international audience needs

Integration with Build System​

Automated Checks​

  • Markdown linting runs as part of CI/CD
  • Link checking should be implemented for external references
  • Spell checking integration recommended
  • Build fails on documentation formatting errors

Version Control​

  • Document significant changes in commit messages
  • Use feature branches for major documentation updates
  • Tag documentation versions with product releases
  • Maintain changelog for documentation updates