I'm building a portal for docs, runbooks, and ownership, how should I structure it?

A good portal for docs + runbooks + ownership should optimize for 3 things:

1. Findability — people can quickly locate the right thing
2. Trust — they know it’s current and who owns it
3. Actionability — they can solve an issue or complete a task without hunting around

A practical structure is:

---

1) Organize by audience + intent, not just by team

Instead of only “Engineering / Product / Ops,” make the top-level paths reflect what people are trying to do:

• Start here
• Services / Systems
• Runbooks
• Operations
• Architecture / Standards
• Ownership
• How-to / SOPs
• Incidents / Postmortems
• Policies / Compliance
• Templates / Contributing

This makes the portal useful for both:

• someone troubleshooting at 2am
• someone onboarding
• someone trying to find the owner of a service

---

2) Core information architecture

Home page

Keep it utility-first:

• Search bar
• Quick links to top runbooks / critical services
• “Recently updated”
• “Most used”
• “Critical alerts / incident links”
• Directory of teams or domains

Service / system pages

Each service should have a standard page template:

• Service name
• What it does
• Owner / backup owner
• Pager / support channel
• SLA/SLO
• Dependencies
• Links to dashboards
• Links to runbooks
• Deployment info
• Architecture diagram
• Common issues
• Related docs
• Last reviewed date

This becomes the canonical page for ownership and operational context.

Runbooks

Structure runbooks by:

• Symptom: “High latency”, “Queue backlog”, “Auth failures”
• Action: “Restart service”, “Rotate key”, “Failover”
• Incident type: “DB outage”, “deploy rollback”, “capacity issue”

Each runbook should have:

• Purpose
• When to use it
• Preconditions / safety notes
• Step-by-step actions
• Validation steps
• Escalation path
• Rollback / fallback
• Owner
• Last tested date

Ownership directory

Make ownership easy to query:

• Team / domain
• Services owned
• Primary and secondary contacts
• On-call schedule
• Slack / Teams channel
• Escalation path
• Location / time zone if relevant

If possible, support:

• Search by service
• Search by person
• Search by team
• Search by tag/domain

---

3) Use a strong metadata model

Every page should have consistent metadata, such as:

• Title
• Type: doc / runbook / service / policy / SOP
• Owner
• Team
• Reviewer
• Last reviewed
• Review cadence
• Status: draft / active / deprecated
• Tags
• System/service name
• Criticality
• Related links

This enables filtering, search, and “staleness” detection.

---

4) Make “owner” and “freshness” impossible to miss

For operational content, prominently show:

• Owner
• Backup owner
• Last verified/tested
• Next review date
• Status

This prevents dead docs from becoming dangerous.

Consider a badge system:

• Green: reviewed recently
• Yellow: due soon
• Red: overdue

---

5) Standardize templates

Templates reduce chaos and improve consistency.

Recommended templates:

• Service page
• Runbook
• SOP / procedure
• Architecture decision record (ADR)
• Incident postmortem
• Troubleshooting guide
• Policy / standard
• Project doc

If every page type looks and behaves predictably, users learn the portal faster.

---

6) Add navigation patterns that match real usage

Good portal navigation usually includes:

• Global search
• Faceted filters
• Breadcrumbs
• Related docs
• “See also” links
• Favorites / pinned items
• Recently viewed
• Suggested docs based on service/team

For runbooks specifically, consider:

• “Start from symptom”
• “Start from service”
• “Start from incident severity”

---

7) Separate “reference” from “procedural” content

These get used differently:

Reference

• Architecture
• Service descriptions
• Policies
• Ownership

Procedural

• Runbooks
• SOPs
• Incident response
• Change steps

The portal should visually distinguish them so people don’t confuse “what exists” with “what to do.”

---

8) Suggested top-level structure

Here’s a concrete structure you could use:

• Home
• Search
• Services
  • Service catalog
  • Critical services
  • By team
• Runbooks
  • By symptom
  • By service
  • By incident type
• Ownership
  • Team directory
  • Service owners
  • On-call / escalation
• Docs
  • How-to
  • SOPs
  • Architecture
  • Standards / policies
• Incidents
  • Active incidents
  • Postmortems
  • Known issues
• Admin / Contribute
  • Templates
  • Doc standards
  • Review process

---

9) Key UX principles

• Search first
• Minimize clicks to owner or action
• Use plain language
• Prefer one canonical page per service
• Link docs together
• Show current state and freshness
• Make it obvious what to do next

---

10) Governance: keep it healthy

A portal fails when no one maintains it. Put in place:

• Required owner for every page
• Review cadence for critical docs
• Deprecation process
• Ownership changes tied to service catalog changes
• Stale doc alerts
• Lightweight contribution workflow

---

11) If you want a very simple MVP

Start with just 4 sections:

1. Search
2. Service catalog
3. Runbooks
4. Ownership directory

Then add:

• SOPs
• architecture
• incidents
• policies

This gives you a useful foundation without overbuilding.

---

If you want, I can also give you:

1. a sample sitemap
2. a page template for service/runbook/ownership pages
3. a database/schema model for the portal