DocOps Callout

1. Introduction

The DocOps Callout Extension allows you to create visually appealing and informative callout visualizations in your AsciiDoctor documents. Callouts are useful for highlighting important processes, metrics, and timelines in a structured and visually engaging way.

This guide will help you understand the basic concepts of callouts, how to include them in your AsciiDoctor documents, and provide examples of different types of callout visualizations.

2. Basic Concepts

2.1. What are Callouts?

Callouts in the DocOps extension are SVG-based visual elements that can be included in your AsciiDoctor documents. Each callout has:

  • A title (the main heading of the callout)

  • A collection of steps or metrics

  • Optional metadata

The extension supports three main types of callout visualizations:

  • Systematic Approach - Displays a step-by-step process with phases, actions, results, and improvements

  • Metrics - Highlights key metrics in a visually appealing format

2.2. Callout Components

2.2.1. Systematic Approach Components

A systematic approach callout includes:

  • A title

  • A series of steps, each with:

  • Phase - The stage or phase of the process

  • Action - What is done during this phase

  • Result - The outcome of the action

  • Improvement (optional) - How this step could be improved

2.2.2. Metrics Components

A metrics callout includes:

  • A title

  • A collection of key-value pairs representing important metrics

3. AsciiDoctor Syntax for Callouts

To include callouts in your AsciiDoctor document, you use a special macro syntax. Here’s the basic format:

[docops,callout,width=800,height=600]
----
title: Your Callout Title
type=systematic
---
Phase | Action | Result | Improvement
Phase 1 | Action 1 | Result 1 | Improvement 1
Phase 2 | Action 2 | Result 2 | Improvement 2
Phase 3 | Action 3 | Result 3 | Improvement 3
----

The macro processes the table data and generates an SVG representation of the callout that is embedded in your document.

3.1. Table Format

The table format uses a simple pipe-separated syntax:

  • The first line after the --- separator is the header row

  • Subsequent rows contain the data for each step

  • For metrics callouts, the table has two columns: Metric Name and Value

3.2. JSON Format

Alternatively, you can use JSON format for more control:

[docops,callout,width=800,height=600]
----
{
  "type": "systematic",
  "title": "Your Callout Title",
  "steps": [
    {
      "phase": "Phase 1",
      "action": "Action 1",
      "result": "Result 1",
      "improvement": "Improvement 1"
    },
    {
      "phase": "Phase 2",
      "action": "Action 2",
      "result": "Result 2",
      "improvement": "Improvement 2"
    }
  ]
}
----

3.3. Callout Parameters

3.3.1. Block Macro Parameters

  • width (optional): The width of the SVG in pixels. Default is 800.

  • height (optional): The height of the SVG in pixels. Default is 600.

3.3.2. Block Body Parameters

  • type (required): The type of callout visualization (systematic, metrics, ). Default is "systematic".

  • title (required): The title of the callout.

4. Examples

4.1. Systematic Approach Example

Here’s an example of a systematic approach callout for a software development process:

[docops,callout]
----
title: Software Development Process
type=systematic
---
Phase | Action | Result | Improvement
Requirements | Gather user needs and system requirements | Detailed requirements document | Involve end-users earlier in the process
Design | Create system architecture and UI/UX designs | Technical specifications and wireframes | Use more design thinking workshops
Development | Implement features according to specifications | Working code with unit tests | Increase pair programming sessions
Testing | Perform QA and user acceptance testing | Bug reports and validation results | Automate more test cases
Deployment | Release to production environment | Live application | Implement more robust CI/CD pipeline
Maintenance | Monitor performance and fix issues | Stable system with ongoing improvements | Establish better feedback loops
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT LicenseSoftware Development Process1RequirementsGather user needs and system requirementsDetailed requirements documentInvolve end-users earlier in the process2DesignCreate system architecture and UI/UX designsTechnical specifications and wireframesUse more design thinking workshops3DevelopmentImplement features according to specificationsWorking code with unit testsIncrease pair programming sessions4TestingPerform QA and user acceptance testingBug reports and validation resultsAutomate more test cases5DeploymentRelease to production environmentLive applicationImplement more robust CI/CD pipeline6MaintenanceMonitor performance and fix issuesStable system with ongoing improvementsEstablish better feedback loops

4.2. Metrics Example

Here’s an example of a metrics callout for a quarterly business performance report:

[docops,callout]
----
title: Q2 2024 Business Performance
type=metrics
---
Metric | Value
Revenue | $2.4M
Growth | 18%
New Customers | 156
Customer Retention | 94%
NPS Score | 72
Average Deal Size | $15,400
Sales Cycle | 32 days
Marketing ROI | 3.2x
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT LicenseQ2 2024 Business Performance📊Revenue$2.4M📊Growth18%📊New Customers156📊Customer Retention94%📊NPS Score72📊Average Deal Size$15,400📊Sales Cycle32 days📊Marketing ROI3.2x

4.3. Creative Examples

4.3.1. Project Retrospective

Use a systematic approach callout to document a project retrospective:

[docops,callout]
----
title: Cloud Migration Project Retrospective
type=systematic
---
Phase | Action | Result | Improvement
Planning | Assessed current infrastructure and defined migration strategy | Comprehensive migration plan with risk assessment | More detailed dependency mapping
Preparation | Set up cloud environment and testing infrastructure | Ready staging environment with monitoring tools | Better documentation of configuration
Pilot Migration | Migrated non-critical applications | Validated approach with minimal disruption | More automated testing of migrated applications
Full Migration | Migrated production workloads in planned waves | Successfully transferred 95% of workloads | Improved communication during cutover periods
Optimization | Refined resource allocation and implemented auto-scaling | 30% cost reduction and improved performance | Earlier implementation of cost management tools
Knowledge Transfer | Trained operations team on new cloud infrastructure | Team capable of managing cloud environment | More hands-on workshops and documentation
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT LicenseCloud Migration Project Retrospective1PlanningAssessed current infrastructure and defined migration strategyComprehensive migration plan with risk assessmentMore detailed dependency mapping2PreparationSet up cloud environment and testing infrastructureReady staging environment with monitoring toolsBetter documentation of configuration3Pilot MigrationMigrated non-critical applicationsValidated approach with minimal disruptionMore automated testing of migrated applications4Full MigrationMigrated production workloads in planned wavesSuccessfully transferred 95% of workloadsImproved communication during cutover periods5OptimizationRefined resource allocation and implemented auto-scaling30% cost reduction and improved performanceEarlier implementation of cost management tools6Knowledge TransferTrained operations team on new cloud infrastructureTeam capable of managing cloud environmentMore hands-on workshops and documentation

4.3.2. Health and Fitness Metrics

Use a metrics callout to track health and fitness progress:

[docops,callout]
----
title: 90-Day Fitness Challenge Results
type=metrics
---
Metric | Value
Weight Loss | 12 lbs
Body Fat Reduction | 4.2%
Muscle Mass Increase | 2.8 lbs
Resting Heart Rate | -8 bpm
VO2 Max Improvement | +5.3 ml/kg/min
Workout Consistency | 87%
Daily Step Average | 11,245
Sleep Quality Score | +18%
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT License90-Day Fitness Challenge Results📊Weight Loss12 lbs📊Body Fat Reduction4.2%📊Muscle Mass Increase2.8 lbs📊Resting Heart Rate-8 bpm📊VO2 Max Improvement+5.3 ml/kg/min📊Workout Consistency87%📊Daily Step Average11,245📊Sleep Quality Score+18%

4.3.3. Customer Journey Map

Use a systematic approach callout to map a customer journey:

[docops,callout]
----
title: E-Commerce Customer Journey
type=systematic
---
Phase | Action | Result | Improvement
Awareness | Customer discovers product through social media ad | Interest in learning more about the product | More targeted ad campaigns based on user interests
Consideration | Customer researches product features and reads reviews | Comparison with competing products | Enhanced product pages with comparison tools
Decision | Customer adds product to cart and completes checkout | Successful purchase | Streamlined checkout process with fewer steps
Delivery | Product is shipped and delivered to customer | Customer receives product | Better tracking and delivery time estimates
First Use | Customer unboxes and begins using the product | Initial experience with product features | Improved unboxing experience and quick-start guides
Support | Customer contacts support with questions | Resolution of customer issues | More proactive support with better documentation
Loyalty | Customer makes repeat purchases and recommends to others | Increased customer lifetime value | Enhanced loyalty program and personalized offers
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT LicenseE-Commerce Customer Journey1AwarenessCustomer discovers product through social media adInterest in learning more about the productMore targeted ad campaigns based on user interests2ConsiderationCustomer researches product features and reads reviewsComparison with competing productsEnhanced product pages with comparison tools3DecisionCustomer adds product to cart and completes checkoutSuccessful purchaseStreamlined checkout process with fewer steps4DeliveryProduct is shipped and delivered to customerCustomer receives productBetter tracking and delivery time estimates5First UseCustomer unboxes and begins using the productInitial experience with product featuresImproved unboxing experience and quick-start guides6SupportCustomer contacts support with questionsResolution of customer issuesMore proactive support with better documentation7LoyaltyCustomer makes repeat purchases and recommends to othersIncreased customer lifetime valueEnhanced loyalty program and personalized offers

4.3.4. Environmental Impact Metrics

Use a metrics callout to highlight environmental sustainability efforts:

[docops,callout]
----
title: Corporate Sustainability Achievements 2024
type=metrics
---
Metric | Value
Carbon Footprint Reduction | 28%
Renewable Energy Usage | 72%
Water Conservation | 350,000 gallons
Waste Diverted from Landfill | 94%
Paper Usage Reduction | 65%
Sustainable Suppliers | 83%
Employee Sustainability Training | 97%
Community Environmental Projects | 12
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT LicenseCorporate Sustainability Achievements 2024📊Carbon Footprint Reduction28%📊Renewable Energy Usage72%📊Water Conservation350,000 gallons📊Waste Diverted from Landfill94%📊Paper Usage Reduction65%📊Sustainable Suppliers83%📊Employee Sustainability Training97%📊Community Environmental Projects12

5. Advanced Usage

5.1. Using JSON Format for Complex Callouts

For more complex callouts, you can use the JSON format directly:

[docops,callout]
----
{
  "type": "systematic",
  "title": "DevOps Implementation Strategy",
  "steps": [
    {
      "phase": "Assessment",
      "action": "Evaluate current development and operations processes",
      "result": "Identified bottlenecks and improvement opportunities",
      "improvement": "More comprehensive stakeholder interviews"
    },
    {
      "phase": "Planning",
      "action": "Define DevOps roadmap and select tools",
      "result": "Strategic implementation plan with tool selection",
      "improvement": "Better alignment with business objectives"
    },
    {
      "phase": "Infrastructure",
      "action": "Implement infrastructure as code and CI/CD pipelines",
      "result": "Automated infrastructure provisioning and deployment",
      "improvement": "More comprehensive testing in pipelines"
    },
    {
      "phase": "Culture",
      "action": "Foster collaboration between development and operations teams",
      "result": "Improved communication and shared responsibility",
      "improvement": "More cross-functional training and workshops"
    },
    {
      "phase": "Monitoring",
      "action": "Implement comprehensive monitoring and alerting",
      "result": "Proactive issue detection and resolution",
      "improvement": "Better correlation between metrics and business impact"
    },
    {
      "phase": "Optimization",
      "action": "Continuously improve processes and automation",
      "result": "Reduced lead time and increased deployment frequency",
      "improvement": "More regular retrospectives and improvement cycles"
    }
  ]
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT LicenseDevOps Implementation Strategy1AssessmentEvaluate current development and operations processesIdentified bottlenecks and improvement opportunitiesMore comprehensive stakeholder interviews2PlanningDefine DevOps roadmap and select toolsStrategic implementation plan with tool selectionBetter alignment with business objectives3InfrastructureImplement infrastructure as code and CI/CD pipelinesAutomated infrastructure provisioning and deploymentMore comprehensive testing in pipelines4CultureFoster collaboration between development and operations teamsImproved communication and shared responsibilityMore cross-functional training and workshops5MonitoringImplement comprehensive monitoring and alertingProactive issue detection and resolutionBetter correlation between metrics and business impact6OptimizationContinuously improve processes and automationReduced lead time and increased deployment frequencyMore regular retrospectives and improvement cycles

5.2. Metrics with Custom Formatting

You can use JSON format to create metrics callouts with custom formatting:

[docops,callout]
----
{
  "type": "metrics",
  "title": "Website Performance Metrics",
  "metrics": {
    "Page Load Time": "1.2s",
    "First Contentful Paint": "0.8s",
    "Time to Interactive": "2.1s",
    "Bounce Rate": "24%",
    "Conversion Rate": "3.8%",
    "Mobile Traffic": "68%",
    "SEO Score": "92/100",
    "Accessibility Score": "97/100"
  }
}
----
DocOps.ioMIT Licensehttps://docops.io2025-06-14Generated by DocOps.io - Licensed under MIT LicenseWebsite Performance Metrics📊Page Load Time1.2s📊First Contentful Paint0.8s📊Time to Interactive2.1s📊Bounce Rate24%📊Conversion Rate3.8%📊Mobile Traffic68%📊SEO Score92/100📊Accessibility Score97/100

6. Conclusion

The DocOps Callout Extension provides a powerful way to enhance your AsciiDoctor documents with visually appealing and informative callout visualizations. By using either the table format or JSON configuration, you can create customized callouts that effectively communicate processes, and metrics.

The extension supports three main types of callouts (systematic, and metrics), making it versatile for different documentation needs. Whether you’re documenting a project retrospective, highlighting key performance indicators, the Callout Extension helps you present information in a clear and engaging way.