IBM (Inquiry-Based Method): Towards Agile Documentation in the Software Development Process

Published in

Nerd For Tech

7 min readFeb 9, 2024

Abstract

In the fast-moving world of software development, documentation is crucial to sharing knowledge and project continuity. However, conventional methods of doing this such as predefined templates or narrative-style documentation still struggle to keep up with structure, dynamic, fast-paced, and collaborative. As software projects become more complex and agile, the need for a more dynamic and collaborative documentation strategy.

In this article we proposed a new strategy title as “Inquiry-Based Method”. IBM serves as an agile strategy guide for software engineers to effectively document their work. This article explores the principles, framework, and advantages of IBM across diverse software development teams.

Introduction

Let’s be real here. Developers don’t always have a burning passion for writing documentation. It’s not that they hate it, but sometimes they’re just too caught up in the whirlwind of coding and debugging to prioritize it. Writing documentation can feel like a big task, especially when there’s a lot of code to deal with and deadlines to meet.

But here’s why documentation is so important? it’s like a map that helps everyone understand the software, not just developers but also future users and people who will maintain it. Without documentation, things get confusing, mistakes happen, and progress slows down.

So, how can we make developers more interested in writing documentation? How can we make it easier and more natural to do? The answer is to be flexible with documentation , to write it as needed and keep it up-to-date as the software develops.

In response, this article proposed a new strategy title as Inquiry-Based Method (IBM) marks a significant change in how software teams handle documentation. Unlike traditional methods, IBM focuses on capturing knowledge through questions. By turning structured elements like epics, user stories, and sub-tasks into questions and methodically answering them, teams can produce documentation that is more structure, dynamic, collaborative, and closely matching the evolving needs of the project.

Principles of IBM

IBM is guided by several key principles that shape its approach and effectiveness including:

Start from Now (Do not look at what has passed, and do not wait until it’s over): Rather to start document what you developed in past, or waiting until the end of a development cycle to document everything, begin documenting as soon as the need arises. This proactive approach ensures that documentation is aligned with the current state of the software and captures relevant information when it’s most needed.
Inquiry-Driven Approach (Be curious and enthusiastic to understand the world around you): Central to IBM is an inquiry-driven approach, where documentation tasks are presented as questions waiting to be answered. This principle motivates teams to actively engage in tackling tasks that are specific and small.
Precision and Relevance (Brevity is the soul of wit): By focusing on answering specific questions, IBM ensures precision and relevance in the documentation produced. Rather than providing overly verbose or generic descriptions.
Cross-Functional Collaboration (Everyone must involve) : By involving individuals from diverse roles and disciplines within the team, teams can leverage a wide range of expertise to generate comprehensive and well-rounded documentation.
Continuous Improvement (Just as software evolves, so does our documentation): IBM emphasizes iterative improvement, recognizing that documentation is an ongoing process. Teams continuously revisit and refine documentation in response to feedback, updates, and changing project requirements, ensuring its accuracy and relevance over time.
Documentation is a living artifact (Our documentation breathes and grows with our projects) : Instead of treating documentation as a static artifact, IBM views it as a living entity that evolves alongside the software development process by keeping it up to date and relevant, reflecting the latest changes and improvements in software functionality and architecture.

Framework of IBM

The IBM framework serves as guides for teams during the documentation process, offering a structured approach for software teams to effectively capture, and organize their work.

A. Epic Identification (the Chapter):

Epic identification is a crucial step in the IBM framework, representing a high-level category within the project that covers specific areas the documentation will focus on. Epic aligns with the traditional notion of organizing documentation efforts into chapters, each covering specific topics or aspects of the software. Here, we define the key documentation focus areas within the project, typically aligning with major components, functionalities, or objectives of the software system, such as system features, workflows, system architecture, user interactions, performance optimization strategies, or security measures.

Epic identification has the following benefits:

Organizing Documentation Efforts: By categorizing documentation requirements into epics, teams can effectively organize their documentation efforts and prioritize their documentation tasks.
Facilitating Cross-Functional Collaboration: By defining documentation focus areas at a high level, epics encourage collaboration and knowledge sharing among team members from diverse disciplines, such as developers, designers, QA, etc.
Adapting to Project Dynamics: As project requirements change or new priorities emerge, teams can adjust their epic definitions accordingly. This allows teams to adapt their documentation efforts to the evolving dynamics of the project.

B. User Story Definition (the Section):

A user story is one of the most common techniques for exploring and understanding the user needs. In addition, its simplicity, easy to learn and understandable. Therefore IBM Framework adapted the user story to support gathering the user documentation needs in a semi-structured way, during the activity. This mirrors the traditional practice of defining for each section and it objectives, outlining the key areas to be covered.

In the IBM Framework, user story plays a pivotal role in shaping the documentation process. It enabling teams to capture diverse documentation needs effectively. Within each epic, user stories are crafted to encapsulate specific documentation requirements, highlighting the key areas that need coverage. For example, a user story within the “system features” epic might focus on documenting a particular feature’s functionality, use cases, and implementation details.

The user story format typically follows a structured template that includes:

Title: A brief description of what being addressed by the user story.
Description: A detailed explanation of the user story, including the goal, the action they need to perform, and the benefit or value they expect to derive from it.
Acceptance Criteria: outline specific conditions or outcomes that must be satisfied for the user story to be considered done.
Priority: The relative importance or urgency of the user story, typically expressed as a numerical value or ranking.
Estimate: the effort or complexity required to apply the user story, often expressed in story points or another unit of measurement. It help teams plan and schedule documentation work more effectively.
Dependencies: dependencies or external factors that may impact on documentation activity, such as reliance on other resources.

Here are some examples of user stories within various epics:

Training and Onboarding Epic: As a trainer, I want documentation of user workflows and usage scenarios with interactive examples and tutorials to facilitate user training and onboarding processes.
Security Epic: As a security auditor, I want detailed documentation of the system’s access control mechanisms and encryption protocols to ensure compliance with regulatory standards.

3. Integration Epic: As an integration specialist, I want documentation of API endpoints and data exchange formats to facilitate seamless integration with third-party systems and services.

C. Sub-Task Breakdown (the Topic):

In traditional documentation practices, breaking down chapters or sections into topics or sub-topic facilitates detailed coverage of specific areas. Similarly, IBM framework. Once we have our user stories. Team start formulate questions that need to be answer and achieving the user story goals. These questions serve as the building blocks for creating comprehensive documentation.

This process work as following:

Question Formulation: Picture each sub-task as a question that needs an answer. For example, if our user story is about a system feature, a sub-task could be, “How does this feature interact with other parts of the system?” The answer to each question forms a crucial part of our documentation.
Assigning Sub-tasks to Team Members: When defining our sub-tasks, they can be assigned to different team members, each with one task. We need to ensure that each person has a clear role to play in the documentation process.

D. Answer Generation & Review:

With the sub-tasks defined, team members collaborate to generate answers to the questions posed by each sub-task. Sub-task answer may take various forms, including written guides, diagrams, code examples, interactive tutorials, or video demonstrations, depending on the nature of the information the need.

Each of team member can work independently to answer the questions posed by their assigned sub-tasks. Once they have their answers, they can collaborate with others to review and refine the content, ensuring accuracy and completeness.

E. Documentation Creation:

As each team member completes their sub-tasks, the larger documentation picture starts to come together. By combining all the individual contributions, we create a comprehensive and cohesive documentation that addresses the main objectives outlined in the epic. The documentation created should address the objectives outlined in the user stories and provide actionable insights and guidance to stakeholders.

F. Iterative Refinement:

Throughout the documentation process, teams engage in iterative refinement, adding another epic, user stories , Sub-task, and improvement of the documentation. The iterative nature of IBM encourages teams to revisit and refine documentation over time. In addition, ensuring that it remains up-to-date, and reflective of the latest developments in the software.

Conclusion

In conclusion, the Inquiry-Based Method (IBM) represents a new agile method in software documentation .It embracing principles including starting documentation from the outset, adopting an inquiry-driven approach, and promoting precision, relevance, and cross-functional collaboration. In addition, IBM offers a flexible and adaptive framework that aligns closely with the evolving needs of software projects. The IBM framework, structured around epic identification, user story definition, sub-task breakdown, answer generation and review, documentation creation, and iterative refinement, provides a systematic approach for teams to effectively capture, organize, and maintain documentation throughout the development lifecycle.

As software development continues to evolve, the need for agile documentation strategies like IBM which empowers teams to overcome the traditional challenges associated with documentation and unlock the full potential of agile development methodologies.