Practice "All Eyes On The Documentation" — Open Reading and Writing for All Stakeholders

This chapter describes “All Eyes On The Documentation,” an approach in which Application Documentation is open not only for reading but also for writing by everyone with a stake in it, and the guardrails that make this approach safe.

The Approach

Under “All Eyes On The Documentation,” all Application Documentation is published to the centralized Digital Library, and that library is open not only for reading but also for writing by everyone with a stake in the Application. People outside the immediate Application team, such as architects, requirements managers, Release Managers, support staff, and testers, can correct anything they know to be wrong as soon as they find it, so that everyone else benefits immediately.

The reasoning is simple. The people who discover that documentation is wrong are frequently not the people responsible for maintaining it. If they can only report the error, the correction waits in someone else’s queue, and in the meantime others are misled by the error. If they can fix it directly, the documentation improves continuously. The version control common in modern Digital Libraries provides the safety net: any change can be seen, attributed, and rolled back.

Establish “All Eyes On The Documentation” with Guardrails

Open documentation works best with four guardrails:

13. Open by default, restricted by exception. All Application Documentation is open for reading and writing unless there is a specific reason to restrict it. Restrictions apply to genuinely sensitive content, such as the locations of Security Secrets and the findings of vulnerability scans and penetration tests.

14. The Application Manager remains accountable. Openness does not dilute accountability. The Application Manager is notified of edits made by others, for example through change notifications or watch lists, and all changes are reviewed at each Release.

15. All edits are attributed. Every change is recorded against the person who made it; anonymous edits are not permitted.

16. Controlled documents follow formal approval. Documents that regulations require to be formally controlled, for example in regulated validation environments, may require formal approval workflows rather than direct editing.

Document and Share the Approach

Publish the enterprise’s “All Eyes On The Documentation” policy and its guardrails in the Digital Library, and make clear to every stakeholder that they are expected to correct what they know to be wrong.

Best Practice: Practice “All Eyes On The Documentation” with Guardrails

It is a best practice to both establish and document the solution for keeping documentation accurate: open Application Documentation for both reading and writing by everyone with a stake in it, protected by version control, restriction by exception, Application Manager accountability, attributed edits, and formal approval where regulation requires it.

Benefits: Opening documentation to everyone with a stake in it multiplies the number of people keeping it accurate, so errors are corrected when they are found rather than when they reach the top of someone’s queue. The guardrails preserve accountability and safety, so that openness improves quality without creating chaos.

Common Antipatterns

Connections to Related IF4IT Practices and Inventories

The GxP Compliance Framework addresses controlled documentation in regulated environments. The Enterprise Inventory Management Best Practices addresses governance of shared enterprise knowledge.