Skip to main content

Agile methodology for documentation

Process Type: Team Methodology
Applies to: Uyuni documentation team operations
Framework: Docs-as-Code with Agile practices
Review Cycle: Continuous improvement through retrospectives

Overview​

The Uyuni documentation team operates using an agile methodology centered around a docs-as-code approach. This methodology treats documentation with the same rigor and processes as software development, ensuring quality, collaboration, and continuous improvement.

Our agile framework combines:

  • GitHub-based planning for transparency and tracking
  • Collaborative workflows for knowledge sharing
  • Iterative delivery of documentation improvements

Core Principles​

Docs-as-Code Philosophy​

Version Control:

  • All documentation stored in Git repositories
  • Changes tracked through pull requests and commits
  • Branching strategies align with software development practices

Collaboration:

  • Peer review processes for all documentation changes
  • Shared ownership and collective responsibility
  • Cross-functional collaboration with development teams

Automation:

  • Continuous integration for documentation builds
  • Automated testing and validation
  • Deployment pipelines for documentation delivery

Quality Assurance:

  • Systematic review processes
  • Consistency through style guides and templates
  • Regular quality audits and improvements

Meeting Cadence and Structure​

Daily Standups (Slack-based)​

Format: Asynchronous Slack communication
Frequency: Daily
Purpose: Quick status updates and coordination

Structure:

  • What did you work on yesterday?
  • What are you working on today?
  • Any blockers or impediments?
  • Any help needed from the team?

Benefits:

  • Maintains team awareness without disrupting deep work
  • Flexible timing across time zones
  • Written record for reference
  • Quick identification of blockers

Weekly Retrospectives​

Schedule: Every Thursday
Duration: 45-60 minutes
Participants: Full Uyuni/MLM team

Agenda:

  1. What went well this week? (5-10 minutes)
  2. What could be improved? (10-15 minutes)
  3. Action items from previous retrospective (5-10 minutes)
  4. New action items and owners (10-15 minutes)
  5. Process improvements (10-15 minutes)

Outcomes:

  • Continuous process improvement
  • Team alignment and communication
  • Issue identification and resolution
  • Culture of learning and adaptation

Biweekly Team Review Meetings​

Schedule: Every two weeks
Duration: 60-90 minutes
Participants: Documentation team + stakeholders

Purpose:

  • Review completed work and deliverables
  • Discuss upcoming priorities and planning
  • Coordinate with other teams and projects
  • Share knowledge and best practices

Agenda:

  1. Sprint review - Completed work demonstration (20-30 minutes)
  2. Metrics and analytics - Team performance and project status (10-15 minutes)
  3. Upcoming work - Next sprint planning discussion (20-30 minutes)
  4. Stakeholder feedback - Input from product and development teams (10-15 minutes)
  5. Team updates - Process changes and announcements (5-10 minutes)

Core Team Meetings​

Schedule: As needed, typically weekly (Wednesday)
Duration: 30-45 minutes
Participants: Core team leads and key contributors

Focus Areas:

  • Strategic planning and roadmap alignment
  • Resource allocation and capacity planning
  • Cross-team coordination and dependencies
  • Escalation and decision-making for complex issues

GitHub-Based Planning​

Project Management​

Planning Tools:

  • GitHub Projects for kanban-style workflow management
  • Issues for task tracking and requirements documentation
  • Milestones for sprint and release planning
  • Labels for categorization and prioritization

Workflow States​

Backlog Management:

  • Backlog: Prioritized list of upcoming work
  • Ready: Items prepared for active development
  • In Progress: Currently being worked on
  • Review: Under peer review or stakeholder review
  • Done: Completed and delivered

Issue Lifecycle​

Creation and Refinement:

  1. Issues created with clear descriptions and acceptance criteria
  2. Labels applied for categorization (priority, type, area)
  3. Assignment to appropriate team members
  4. Estimation and planning discussions

Execution and Tracking:

  1. Regular status updates in issue comments
  2. Linking to related pull requests and branches
  3. Progress tracking through project boards
  4. Completion verification and closure

Collaboration Workflows​

Code Review Process​

Pull Request Standards:

  • Clear description of changes and rationale
  • Reference to related issues and requirements
  • Self-review completed before requesting reviews
  • Appropriate reviewers assigned based on expertise

Review Criteria:

  • Content accuracy and technical correctness
  • Style consistency with team guidelines
  • Completeness of documentation coverage
  • User experience and accessibility considerations

Knowledge Sharing​

Documentation Standards:

  • Consistent formatting and structure
  • Clear writing and appropriate audience targeting
  • Regular updates and maintenance
  • Cross-references and linking strategies

Team Learning:

  • Regular sharing sessions during team meetings
  • Documentation of lessons learned and best practices
  • Mentoring and pair working opportunities
  • External training and conference participation

Continuous Improvement​

Metrics and Measurement​

Key Performance Indicators:

  • Documentation coverage and completeness
  • Review cycle time and quality
  • User feedback and satisfaction scores
  • Team velocity and capacity utilization

Regular Assessment:

  • Weekly retrospective feedback
  • Monthly team health and satisfaction surveys
  • Quarterly process effectiveness reviews
  • Annual methodology and tool evaluations

Adaptation and Evolution​

Process Refinement:

  • Regular evaluation of meeting effectiveness
  • Tool and technology updates
  • Workflow optimization based on team feedback
  • Integration of industry best practices

Learning Culture:

  • Experimentation with new approaches
  • Failure tolerance and learning opportunities
  • External best practice adoption
  • Team skill development and growth

Best Practices​

Meeting Effectiveness​

Preparation:

  • Clear agendas distributed in advance
  • Pre-meeting material review
  • Action item tracking and follow-up
  • Time management and focused discussions

Participation:

  • Active engagement from all team members
  • Respectful and constructive communication
  • Balanced speaking time and inclusive discussions
  • Documentation of decisions and next steps

Planning Excellence​

Estimation and Capacity:

  • Realistic work estimates based on historical data
  • Buffer time for unexpected work and interruptions
  • Regular capacity planning and resource allocation
  • Stakeholder communication about timelines and priorities

Quality Focus:

  • Definition of done criteria for all work items
  • Regular quality audits and improvement initiatives
  • User-centered design and feedback integration
  • Continuous testing and validation processes

Tools and Technology​

Primary Tools​

Planning and Tracking:

  • GitHub Projects and Issues
  • GitHub Milestones and Labels
  • Team calendars and scheduling tools

Communication:

  • Slack for daily standups and informal communication
  • Video conferencing for formal meetings
  • Email for external stakeholder communication

Documentation:

  • Git repositories for version control
  • Markdown and MDX for content creation (This documentation)
  • Asciidoctor and Antora for enterprise-level documentation
  • Automated build and deployment pipelines
  • Analytics and performance monitoring tools

Integration Points​

Development Team Coordination:

  • Shared project boards and issue tracking
  • Regular cross-team communication
  • Aligned release cycles and planning
  • Joint retrospectives and improvement initiatives

This agile methodology ensures that the documentation team operates efficiently, collaboratively, and continuously improves while delivering high-quality documentation that serves our users effectively.