DocOps Swimlane

1. Introduction

The DocOps Swimlane Extension allows you to create visually appealing and informative swimlane diagrams in your AsciiDoctor documents. Swimlanes are useful for visualizing workflows, processes, and project statuses in a structured and visually engaging way.

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

2. Basic Concepts

2.1. What are Swimlanes?

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

A title (the main heading of the diagram)
Multiple lanes (columns), each with its own title
Items within each lane, each with a title and content
Optional theme configuration (light or dark)

Swimlanes are particularly useful for:

Visualizing workflow stages (e.g., To Do, In Progress, Done)
Showing project status across different teams or components
Representing process flows with parallel activities
Organizing tasks or features by category or status

2.2. Swimlane Components

A swimlane diagram includes:

A title for the overall diagram
Multiple lanes (columns), each with:
A lane title (header)
One or more items containing:
An item title
Item content (bullet points or text)

3. AsciiDoctor Syntax for Swimlanes

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

[docops,swim,width=900,height=450]
----
title=Your Swimlane Title
dark=false
width=900
height=450
---
## Lane 1 Title
### Item 1 Title
- Item 1 content point 1
- Item 1 content point 2

## Lane 2 Title
### Item 2 Title
- Item 2 content point 1
- Item 2 content point 2

## Lane 3 Title
### Item 3 Title
- Item 3 content point 1
- Item 3 content point 2
----

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

3.1. Table Format

The table format uses a simple markdown-like syntax:

Configuration parameters are specified before the --- separator
Each lane starts with ## Lane Title
Each item within a lane starts with # Item Title
Content points are listed with bullet points (- or *)

3.2. JSON Format

Alternatively, you can use JSON format for more control:

[docops,swim,width=900,height=450]
----
{
  "title": "Your Swimlane Title",
  "useDarkTheme": false,
  "width": 900,
  "height": 450,
  "lanes": [
    {
      "title": "Lane 1 Title",
      "items": [
        {
          "title": "Item 1 Title",
          "content": [
            "Item 1 content point 1",
            "Item 1 content point 2"
          ]
        }
      ]
    },
    {
      "title": "Lane 2 Title",
      "items": [
        {
          "title": "Item 2 Title",
          "content": [
            "Item 2 content point 1",
            "Item 2 content point 2"
          ]
        }
      ]
    },
    {
      "title": "Lane 3 Title",
      "items": [
        {
          "title": "Item 3 Title",
          "content": [
            "Item 3 content point 1",
            "Item 3 content point 2"
          ]
        }
      ]
    }
  ]
}
----

3.3. Swimlane Parameters

3.3.1. Block Macro Parameters

width (optional): The width of the SVG in pixels. Default is 900.
height (optional): The height of the SVG in pixels. Default is 450.

3.3.2. Block Body Parameters

title (required): The title of the swimlane diagram.
dark or useDarkTheme (optional): Whether to use dark theme. Default is false.
width (optional): The width of the SVG in pixels. Default is 900.
height (optional): The height of the SVG in pixels. Default is 450.

4. Examples

4.1. Basic Swimlane Example

Here’s an example of a basic swimlane diagram for a software development workflow:

[docops,swim]
----
title=Software Development Workflow
---
## To Do
### Planned Tasks
- Design new dashboard widgets
- Implement two-factor auth
- Refactor the caching layer
- Write API documentation
- Update user interface

## In Progress
### Current Development
- Backend services for dashboard
- Waiting for UI mockups to proceed with front-end implementation
- Expected completion by end of sprint

## Done
### Completed Tasks
- Fixed authentication bug
- Updated third-party libraries
- Optimized database queries
- Enhanced error handling
- All items have been deployed to production successfully
----

4.2. Dark Theme Example

Here’s the same example with dark theme enabled:

[docops,swim]
----
title=Software Development Workflow
dark=true
---
## To Do
### Planned Tasks
- Design new dashboard widgets
- Implement two-factor auth
- Refactor the caching layer
- Write API documentation
- Update user interface

## In Progress
### Current Development
- Backend services for dashboard
- Waiting for UI mockups to proceed with front-end implementation
- Expected completion by end of sprint

## Done
### Completed Tasks
- Fixed authentication bug
- Updated third-party libraries
- Optimized database queries
- Enhanced error handling
- All items have been deployed to production successfully
----

4.3. Creative Examples

4.3.1. Project Roadmap

Use a swimlane diagram to visualize a project roadmap by quarter:

[docops,swim]
----
title=2024 Product Roadmap
---
## Q1 2024
### Core Features
- User authentication improvements
- Performance optimization
- Mobile responsive design

### Infrastructure
- Cloud migration
- CI/CD pipeline setup
- Monitoring and alerting

## Q2 2024
### Core Features
- Advanced search functionality
- User dashboard redesign
- Reporting module

### Infrastructure
- Database scaling
- Caching layer implementation
- Load balancing

## Q3 2024
### Core Features
- AI-powered recommendations
- Social sharing integration
- Custom theming options

### Infrastructure
- Microservices architecture
- GraphQL API
- Data warehouse setup

## Q4 2024
### Core Features
- Enterprise SSO integration
- Advanced analytics
- Workflow automation

### Infrastructure
- Global CDN deployment
- Disaster recovery improvements
- Security hardening
----

4.3.2. Team Responsibilities

Use a swimlane diagram to visualize responsibilities across different teams:

[docops,swim]
----
title=Project Responsibilities by Team
---
## Product Team
### Research & Planning
- Market research
- User interviews
- Feature prioritization
- Roadmap planning

### Documentation
- Product requirements
- User stories
- Acceptance criteria
- Release notes

## Design Team
### UX Design
- User flows
- Wireframes
- Usability testing
- Design system maintenance

### UI Design
- Visual design
- Prototyping
- Asset creation
- Design QA

## Engineering Team
### Frontend
- Component development
- Integration with APIs
- Performance optimization
- Browser compatibility

### Backend
- API development
- Database design
- Security implementation
- Scalability planning

## QA Team
### Testing
- Test planning
- Automated testing
- Manual testing
- Regression testing

### Quality Assurance
- Bug tracking
- Performance monitoring
- Security validation
- Accessibility compliance
----

5. Advanced Usage

5.1. Using JSON Format for Complex Swimlanes

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

[docops,swim]
----
{
  "title": "Customer Journey Map",
  "useDarkTheme": false,
  "width": 900,
  "height": 450,
  "lanes": [
    {
      "title": "Awareness",
      "items": [
        {
          "title": "Channels",
          "content": [
            "Social media",
            "Search engines",
            "Word of mouth",
            "Advertising"
          ]
        },
        {
          "title": "Customer Actions",
          "content": [
            "Discovers brand",
            "Initial research",
            "Follows social accounts"
          ]
        }
      ]
    },
    {
      "title": "Consideration",
      "items": [
        {
          "title": "Channels",
          "content": [
            "Website",
            "Product reviews",
            "Comparison sites",
            "Email marketing"
          ]
        },
        {
          "title": "Customer Actions",
          "content": [
            "Detailed research",
            "Feature comparison",
            "Price checking",
            "Reading reviews"
          ]
        }
      ]
    },
    {
      "title": "Purchase",
      "items": [
        {
          "title": "Channels",
          "content": [
            "E-commerce site",
            "Physical store",
            "Sales representatives",
            "Partner retailers"
          ]
        },
        {
          "title": "Customer Actions",
          "content": [
            "Product selection",
            "Adding to cart",
            "Checkout process",
            "Payment"
          ]
        }
      ]
    },
    {
      "title": "Retention",
      "items": [
        {
          "title": "Channels",
          "content": [
            "Customer support",
            "Email",
            "Mobile app",
            "Community forums"
          ]
        },
        {
          "title": "Customer Actions",
          "content": [
            "Product usage",
            "Support requests",
            "Feature discovery",
            "Repeat purchases"
          ]
        }
      ]
    }
  ]
}
----

6. Conclusion

The DocOps Swimlane Extension provides a powerful way to enhance your AsciiDoctor documents with visually appealing and informative swimlane diagrams. By using either the table format or JSON configuration, you can create customized swimlanes that effectively communicate workflows, processes, and project statuses.

The extension supports both light and dark themes, making it versatile for different documentation needs. Whether you’re documenting a project roadmap, visualizing a workflow, or organizing tasks by status, the Swimlane Extension helps you present information in a clear and engaging way.