Workflow Templates

This directory contains reusable templates for common workflows. These templates provide a starting point for documenting new workflows and ensure consistency across all workflow documentation.

Available Templates

workflow-template.md

Basic template for any workflow documentation. Includes all required sections and formatting guidelines.

runbook-template.md

Template for operational runbooks with step-by-step procedures, checkpoints, and rollback instructions.

troubleshooting-template.md

Template for troubleshooting guides with symptom identification, root cause analysis, and resolution steps.

integration-template.md

Template for documenting integrations with external systems, including authentication, data flow, and error handling.

Using Templates

Creating a New Workflow Document

Choose the appropriate template based on your workflow type
Copy the template to the relevant workflow directory
Rename the file to match your workflow (e.g., create-environment.md)
Fill in all sections following the guidelines in the template
Add diagrams where they improve understanding
Test all commands and code examples
Review for completeness and accuracy

Template Structure

All templates follow a consistent structure:

# Workflow Name

## Overview
Brief description of what this workflow accomplishes

## Prerequisites
- Required tools and access
- Pre-conditions that must be met
- Knowledge requirements

## Steps
1. **Step Name**
   - Detailed instructions
   - Commands to run
   - Expected output

## Validation
How to verify the workflow completed successfully

## Troubleshooting
Common issues and their solutions

## Related Workflows
Links to related procedures

Best Practices

Writing Clear Instructions

Use numbered steps for sequential tasks
Use bullet points for non-sequential items
Bold important terms and UI elements
Include code blocks for commands
Add notes for important information
Provide examples where helpful

Code Examples

Always test and format code examples properly:

# Good: Clear, tested command with comments
kubectl get pods -n ephemeral-pr-123 -o wide
# This shows all pods in the PR environment namespace

# Good: Complete, runnable code with error handling
async def create_environment(name: str) -> Environment:
    """Create a new ephemeral environment."""
    try:
        env = await environment_service.create(name)
        logger.info(f"Created environment: {env.name}")
        return env
    except Exception as e:
        logger.error(f"Failed to create environment: {e}")
        raise

Diagrams

Include diagrams using Mermaid syntax where helpful:

graph LR A[User Request] --> B[Validation] B --> C{Valid?} C -->|Yes| D[Create Resources] C -->|No| E[Return Error] D --> F[Update Status]

Workflow Categories

Templates should be placed in the appropriate category:

Core - Essential platform operations
Operational - Day-to-day procedures
Security - Security-related workflows
Integration - External system connections
Developer - Development workflows

Maintenance

Keeping Templates Current

Review templates quarterly
Update with new best practices
Add new templates as needed
Remove obsolete templates
Gather feedback from users

Version Control

Track changes in Git
Use meaningful commit messages
Tag major template updates
Document breaking changes

Contributing

To contribute a new template:

Create the template following existing patterns
Include all standard sections
Add examples and use cases
Test with a real workflow
Submit PR with description

Example Usage

Creating an Environment Workflow

Using workflow-template.md:

# Create Ephemeral Environment

## Overview
This workflow creates a new ephemeral environment for testing pull requests...

## Prerequisites
- Access to Blueberry API
- Valid authentication token
- Understanding of environment naming conventions

## Steps
1. **Prepare environment request**
   ```bash
   curl -X POST https://blueberry.example.com/api/environments \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"name": "pr-123", "ttl": "24h"}'
   ```

[Continue with remaining sections...]

Document ID: workflows/templates/README

Table of Contents