mainwp.dev/guides/templates

MainWP Documentation Templates

This directory contains templates and resources for creating consistent, beginner-friendly documentation for the MainWP.dev project. These templates implement the design principles and standards outlined in our documentation strategy.

Available Templates

Guide Template

File: guide-template.md

A comprehensive template for creating new how-to guides. This template includes:

• Difficulty level indicator
• "What You'll Learn" section
• Prerequisites checklist
• Estimated time to complete
• Quick start section for experienced developers
• Step-by-step instructions with code examples
• Common challenges and solutions
• Best practices
• Testing instructions
• Next steps and related resources

Usage: Copy this template when creating new how-to guides or updating existing guides to follow the new format.

Getting Started Template

File: getting-started-template.md

A template for the main "Getting Started" guide that serves as an entry point for beginners. This template includes:

• Visual development journey flowchart
• Progress indicators for each step
• Clear, numbered steps with visual aids
• Decision trees for choosing between extension and integration development
• Essential resources and next steps

Usage: Use this template to create the main getting started guide that will serve as the primary entry point for new developers.

Getting Started Index Template

File: getting-started-index-template.md

A template for the main documentation landing page that organizes guides into categories with a card-based layout. This template includes:

• Documentation overview flowchart
• Card-based layout for different guide categories
• Difficulty level indicators
• Estimated time to complete
• Visual organization of content

Usage: Use this template to create the main index page for the guides section.

Terminology Glossary

File: terminology-glossary.md

A comprehensive glossary of MainWP terminology to ensure consistent usage across all documentation. This includes definitions for:

• Core concepts
• Development concepts
• User interface terms
• Data management terms
• Security terms
• Technical terms
• MainWP-specific features
• Third-party integration terms

Usage: Reference this glossary when writing documentation to ensure consistent terminology. Link to this glossary from other guides when introducing technical terms.

Code Review Checklist

File: code-review-checklist.md

A detailed checklist for reviewing code examples in documentation to ensure they follow best practices and coding standards. This checklist covers:

• Formatting and style
• WordPress coding standards
• Security practices
• Error handling
• MainWP-specific standards
• Performance considerations
• Defensive programming
• Documentation
• Compatibility
• Testing considerations

Usage: Use this checklist when reviewing and updating code examples in documentation to ensure they follow best practices and coding standards.

Documentation Styles

File: documentation-styles.css

CSS styles for enhancing the visual presentation of documentation, particularly for the card-based layout in the getting-started-index-template.md file. These styles include:

• Color variables for consistent theming
• Typography styles
• Card layout styles
• Difficulty level indicators
• Button styles
• Progress indicators
• Responsive design adjustments

Usage: Include this CSS file when rendering the documentation to enhance its visual presentation.

How to Use These Templates

1. Creating New Guides:

   • Copy the appropriate template (usually guide-template.md)
   • Fill in the sections with your content
   • Ensure you include all required sections
   • Follow the formatting and structure of the template

2. Updating Existing Guides:

   • Compare the existing guide to the template
   • Add any missing sections
   • Restructure content to match the template format
   • Ensure code examples follow the standards in the code review checklist

3. Maintaining Consistency:

   • Use the terminology glossary to ensure consistent terminology
   • Follow the code review checklist for all code examples
   • Maintain the visual style defined in the documentation styles

File Size Management

When creating or updating documentation:

• Target keeping markdown files under 800 lines when possible
• For longer guides, split content into logical parts:
  • Main guide (core concepts and implementation)
  • Part 2 (advanced techniques and edge cases)
  • Quick Start guide (condensed version for experienced developers)
• Ensure clear navigation between related parts
• Add cross-references between related guides

Best Practices

1. Beginner-Friendly Content:

   • Start with the basics and gradually introduce more complex concepts
   • Use clear, concise language
   • Avoid jargon without explanation
   • Include visual aids (diagrams, flowcharts) to help conceptual understanding

2. Code Examples:

   • Follow WordPress coding standards
   • Include proper error handling
   • Add comments to explain complex logic
   • Ensure security best practices
   • Test all code examples

3. Visual Structure:

   • Use consistent headings and subheadings
   • Break long content into digestible chunks
   • Use lists and tables for structured information
   • Include difficulty level indicators

4. Cross-Referencing:

   • Link to related guides
   • Reference the API documentation for formal definitions
   • Link to GitHub for implementation examples
   • Link to the terminology glossary for technical terms