"We value working software more than comprehensive documentation."
Although documentation is considered important, is functioning software more important?
On December 4, 2020, an online breakfast on the topic of "Documentation in an Agile Context" took place. Due to the current situation, the event was held online as a live event via Microsoft Teams. Thirty-three participants accepted the invitation. The participants came from many different industries and held various roles (PO, BE, RE, etc.). The speakers shared their knowledge and experience on the topic from diverse perspectives, which are described below. Afterwards, they answered participants' questions. For those who were unable to attend, the livestream was recorded. The content is briefly described below. References for the livestream, which can be ordered from Infometis, are also provided there.
Milica Trajkovic
Business Solutioneer
One of the four values in the Agile Manifesto states that working software is valued more than comprehensive documentation. However, both extremes (no documentation vs. all information in the documentation) are unhelpful because they fail to achieve the goal of conveying an understanding of the subject matter . Therefore, it is recommended to use documentation as a means to an end and to contrast it with other communication channels, such as direct communication. Direct communication is particularly important in the agile age, and thanks to short question-and-answer cycles, requirements can be defined or implemented more clearly and quickly. Therefore, detailed documentation is not needed during this phase, where the requirements are being discussed.
The approaches to documentation in an agile context are as follows: Documentation should be…
– needs-based and straightforward
– containing only the necessary details.
– created "just in time" to ensure that no outdated information is documented.
– reused from workshops, drawings, and diagrams whenever possible.
– easily accessible to the target audience.
– developed collaboratively within the team.
Reference to the livestream:
Introduction from 00:08:39 to 00:20:16;
Documentation in the agile age from 00:12:16 to 00:20:25
Dr. Patrick Steiger
Business Solutioneer
Building on the previous topic, the settings (context) and types of documentation were presented. The question of for whom we document was also addressed. The context analysis assesses communication and collaboration, the maturity of the agile development team, the organizational approach, the industry, and the type of development. There are various types of documentation that must be clearly distinguished. At the highest level, a distinction is made between sustainable product documentation and short-term requirements documentation. Sustainable product documentation encompasses functional, technical, and test documentation. Temporary requirements documentation is further divided into project documentation and implementation content. Regarding product documentation, the question of for whom we document was answered as follows: for ourselves, for further development, for the user, for operations, and for revision. The same question regarding requirements documentation can be answered as follows: for the entire project team, the product owner, the client, suppliers and other teams, as well as stakeholders in general. [
Reference to the livestream:
Which documentation in which setting?]
from 00:20:37 to 00:38:19
Bernhard Fuchs
Automation Genius
The documentation was then examined from a tester's perspective and illustrated with practical examples. For testing, documentation is a crucial part of the work and should be concise and graphical, including relevant content such as the expected result and test data. It is essential that it is completed in a timely manner. Insufficient documentation has a significant impact on project implementation because clarifying questions leads to additional time expenditure and complicates testing. Furthermore, inadequate documentation can make it difficult to reach certain contacts. Regarding types of documentation, from a testing perspective, conceptual test design and regression test cases are particularly important for sustainable documentation. For requirements documentation, test concepts and data, as well as suitable bug reports and test reports, are essential. Visualizations or a user story map are helpful for better understanding the test object.
Reference to the livestream
"Agile Documentation from a Testing Perspective"
from 00:38:20 to 00:54:00
Anja Zhuchkova
Atlassian Consultant
The tools in the Atlassian suite offer a high level of support for agile documentation. Confluence offers the most tools, as it was designed from the outset to simplify documentation and thus free up more time for development. In our view, the following integrated features are essential for making documentation easier for employees:
– Predefined best practices and custom templates
– Simultaneous editing and versioning of pages
– Bidirectional connection with Jira
– Rapid feedback through inline comments and notifications
– Simple permission management
– Various extensions and integration options (Office integration, diagrams, videos, etc.)
– Location-independent access via web browser and mobile app.
Besides Confluence, Jira also offers important tools that support direct communication as well as product and project documentation. These include notifications, comments, test management integrations, and various features for agile ceremonies.
Reference to the livestream
tools for supporting agile documentation
from 00:54:06 to 01:09:00
Q&A session from 01:10:00
As can be read, the complex topic of the documentary was presented from various perspectives and with extensive expert knowledge.
Do you need support in developing a documentation strategy? Please feel free to contact Dr. Patrick Steiger or Milica Trajkovic. We offer a company course tailored to your specific context and will develop the right strategy for you through workshops.
Below are some insights into what went on behind the scenes at this Teams Live event:
