Adding Operational Notes
Learn how to capture operational knowledge using operational note blocks, making critical deployment and runtime information discoverable.
Operational knowledge often lives in Slack threads, runbooks scattered across tools, and the heads of senior engineers. When incidents happen at 3am, this knowledge is hard to find. Operational note blocks capture critical operational information directly in architecture documentation where engineers will find it.
Why Document Operational Knowledge
Operations teams accumulate knowledge that rarely makes it into documentation:
Adding an Operational Note Block
Operational Note Fields
This example uses the NeoArc Operational Note content block.
Categories of Operational Notes
This example uses the NeoArc Operational Note content block.
Placement in Documentation
Place operational notes where engineers will find them:
| Location | Content |
|---|---|
| Service overview pages | Service-specific issues |
| Deployment documentation | Deployment concerns |
| Near related architecture content | Contextual issues |
Keeping Notes Current
Operational notes can become outdated when issues are fixed or circumstances change. Review notes when:
| Trigger | Action |
|---|---|
| Deploying fixes | Update notes for documented issues |
| Changing infrastructure | Review affected notes |
| Incident retrospectives | Add new notes or update existing ones |
Set the status to "obsolete" rather than deleting, to preserve the historical record.
Operational notes appear throughout this documentation site wherever operational context is relevant, demonstrating how to integrate runtime knowledge with architecture content.