Pair Documenting – A Strategy for Better Software Documentation

Just like "great power comes with great responsibility," great software comes with great documentation.

Software Project Managers often struggle with the challenge of ensuring proper documentation in a development project. Surprisingly, even the best-written code can suffer from below-average documentation.

Many initiatives, such as Swagger or APIdocs, aim to improve documentation, but they are designed by and for software engineers. However, documentation should cater to a broader audience—system administrators, decision-makers, potential customers, and integrators.

For developers, a Swagger interface might suffice, but it lacks the broader context: What does the data being processed actually represent? What value does this platform provide?

The Importance of Narrative Documentation A well-written narrative description offers clear advantages over purely technical documentation:

• Improved Readability – It provides an easy-to-follow introduction to the project without requiring readers to piece together meaning from technical details.
• Top-Down Understanding – A high-level view before diving into specifics helps readers gain a structured, meaningful understanding of the system.
• Efficient Knowledge Transfer – Story-driven documentation ensures that when knowledge is handed over, it includes not just facts but also the reasoning behind design choices, saving valuable time.

A Practical Example Consider the following two documentation styles:

Example 1 (Purely Technical Documentation):

SELECT object_type, axis_one, axis_two, tiltmeter_id
FROM "db"."measurements"
GROUP BY "tiltmeter_id"
WHERE "object_type" == 'tiltmeter'
WHERE "axis_one" > threshold OR "axis_two" > threshold
TRIGGER HTTPOUT as 'alert'
TRIGGER QUEUEOUT as 'alert'
EVERY 2s
PERIOD 10s
        

Example 2 (Contextualized Documentation with Explanation):

The system processes data from a two-axis inclinometer sensor (Tiltmeter). Every two seconds, the system queries the database for the most recent 10 seconds of measurements. If a sensor's axis_one or axis_two value exceeds the threshold, an HTTP and QUEUE message is triggered. These events are managed through a TICK script, a SQL-like language used by Kapacitor.

SELECT object_type, axis_one, axis_two, tiltmeter_id
FROM "db"."measurements"
GROUP BY "tiltmeter_id"
WHERE "object_type" == 'tiltmeter'
WHERE "axis_one" > threshold OR "axis_two" > threshold
TRIGGER HTTPOUT as 'alert'
TRIGGER QUEUEOUT as 'alert'
EVERY 2s
PERIOD 10s
        

Once an alert is triggered, the data is sent to a queue (RabbitMQ), where additional metadata (such as location coordinates) is added. The enriched data is then forwarded as a tentative incident to the incident validation component (detailed in Section 10.4.5).

Both examples contain the same SQL script, but the second one provides much-needed context, making it useful to a wider audience. A developer may focus on the SQL, but a decision-maker or system administrator benefits from the explanation.

How Can We Ensure Better Documentation? Can we simply require developers to write comprehensive documentation? This approach often fails—expecting developers to have a top-down perspective, strong writing skills, and the time to document extensively is unrealistic.

Can project managers do it? Not entirely—they lack deep familiarity with the code itself.

A Possible Solution: Pair Documenting Just as QA engineers and security specialists handle tasks that developers may not, technical writers exist to fill the documentation gap. However, if hiring a technical writer isn’t an option, an alternative approach is Pair Documenting—an effective and even enjoyable solution.

How Pair Documenting Works

Pair Documenting follows a model similar to pair programming and involves collaboration between:

• The Developer – The person who wrote or understands the code best, capable of running scripts and making live modifications.
• The Project Manager – Someone who understands project requirements, expected outcomes, and stakeholder needs but isn’t deeply familiar with the code.

Both participants sit together, each with their laptop, working through the documentation collaboratively. This can happen in two ways:

1. Project Manager-Led Approach – The Project Manager reads the project documentation, identifying gaps and asking questions. The Developer explains relevant parts of the code, clarifies how different components interact, and provides insights that fill in missing details.
2. Developer-Led Approach – The Developer explains their work, demonstrating inputs and outputs, UI behavior, logs, and system interactions. The Project Manager then ensures that the explanations align with the project's overall objectives and documentation structure.

Throughout this process, the Project Manager continuously reassesses the documentation, making necessary revisions to maintain clarity and consistency. This approach fosters a feedback loop that strengthens documentation quality, addressing gaps that might otherwise go unnoticed.

Benefits of Pair Documenting

• Efficiency – Real-time collaboration eliminates back-and-forth email chains and speeds up documentation.
• Higher Quality – Combining technical knowledge with project context results in clearer, more useful documentation.
• Improved Project Understanding – Encourages discussions that clarify project goals and system behavior for both parties.

Does It Really Work?

Nice theory, but does it work in practice?

Yes! When integrated with iterative methodologies like Scrum or Kanban, Pair Documenting ensures that documentation is consistently updated and remains concise, focusing on code produced in the latest iteration.

By making documentation a collaborative effort rather than an afterthought, teams can create better software—and better documentation—without over-burdening individual contributors.