Stop Documentation Drift: Tying Technical Docs Directly to Code

Confluence Docs Lie. Tie Your Documentation to Code Instead.

Engineer Kyryl identifies a structural failure in external documentation tools like Confluence. When docs live separately from code, they inevitably drift into fiction regardless of team discipline.

Why This Matters

The gap between code and external documentation creates a recurring cost where developers, BAs, and PMs rely on stale information or waste time on manual clarification. While separate artifacts are easier to mandate initially, they create compounding documentation debt that is accelerated by the increased velocity of AI-generated code.

Key Insights

• Living Contracts: Using springdoc-openapi transforms Swagger UI into a real-time contract generated directly from REST controllers (2026).
• Schema-Level Metadata: PostgreSQL ‘COMMENT ON’ allows DDL comments to ship within migration files, ensuring updates occur in the same PR as schema changes.
• Spec-Driven Communication: The Avro ‘doc’ attribute provides consumers with essential event context directly via the Schema Registry.

Working Examples

Implementing Swagger annotations on Spring Boot REST controllers for automated API documentation.

@RestController
@RequestMapping("/api/orders")
@Tag(name = "Orders", description = "Order lifecycle management")
public class OrderController {
@Operation(
summary = "Get order by ID",
description = "Returns a single order. 404 if the order doesn't exist or belongs to a different customer."
)
@ApiResponse(responseCode = "200", description = "Order found")
@ApiResponse(responseCode = "404", description = "Order not found")
@GetMapping("/{id}")
public ResponseEntity<OrderDto> getOrder(
@Parameter(description = "Internal order ID") @PathVariable Long id
) {
return orderService.findById(id)
.map(ResponseEntity::ok)
.orElse(ResponseEntity.notFound().build());
}
}

Using PostgreSQL COMMENT ON syntax to embed descriptions directly into the database schema.

CREATE TABLE orders (
id BIGSERIAL PRIMARY KEY,
customer_id BIGINT NOT NULL,
status VARCHAR(20) NOT NULL,
total_cents BIGINT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
COMMENT ON TABLE orders IS 'Customer purchase orders. One row per order, regardless of item count.';
COMMENT ON COLUMN orders.status IS 'Order lifecycle state. Valid values: PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED.';
COMMENT ON COLUMN orders.total_cents IS 'Order total in cents. Always positive. Divide by 100 for display.';

Utilizing the doc field in Avro schemas for Kafka message contracts.

{
"type": "record",
"name": "OrderCreatedEvent",
"namespace": "com.example.events",
"doc": "Published when a new order is placed.",
"fields": [
{"name": "orderId", "type": "long", "doc": "Internal order ID from the orders table."},
{"name": "customerId", "type": "long", "doc": "References users.id."}
]
}

Practical Applications

• . Use Case: Product Managers using Swagger UI to verify endpoint parameters during design discussions without developer intervention. Pitfall: Relying on PR templates as reminders to update external wikis; results in stale docs as tickets are closed without wiki updates.
• . Use Case: BAs utilizing AI assistants to query database DDL files containing COMMENT ON entries to understand data relationships. Pitfall: Adding columns via migrations without adding corresponding comments; results in loss of institutional knowledge during PR reviews.

References:

• https://dev.to/code_with_kyryl/confluence-docs-lie-tie-your-documentation-to-code-instead-1nnl