Beanfield · Sep 2026 to now
IPTV knowledge vault
One engineer, one platform, dozens of systems from three vendors. I built a linked knowledge vault of the entire IPTV platform: every system, symptom, log, incident and ruling on its own page, every fact pointing at the file it came from, and a weekly check that flags any page whose source has moved on.
Why it exists
The IPTV platform spans set-top boxes, home Wi-Fi, fibre, the access network, the headend, recorders, storage, middleware, billing and three vendors' portals. The knowledge lived in vendor PDFs, tickets, chat threads, logs and people's heads. A customer ticket could need five systems and a dozen facts before the first useful step.
- Facts scattered across vendor guides, tickets, mirrors and chat
- No single map from a customer symptom to the system at fault
- Documents drifted out of date silently
- New staff had no starting point
- One linked vault, one page per system, symptom and procedure
- Symptom decision trees and fault-path maps from the TV to the vendor
- Every page names its sources; a weekly check flags drift
- Read
hot, thenindex, then the page in front of you
Design decisions
- The project stays the source of truth. The vault is a reading layer. A fact is fixed in the project file first, then the page is refreshed. Every page carries a
project_sourceslist in its front matter. - One page per thing. Each system page has the same shape: access, what it is used for, traps, links and sources. Big systems (the monitoring host, the middleware, telemetry, billing, the service catalogue) are hubs with component and tool pages beneath them.
- Start from the customer. The CX Troubleshooting area opens with symptoms (freezing, no channels, recording missing, wrong guide) and walks down decision trees to the layer at fault.
- A hot cache.
hot.mdholds the newest context in a few screens, so anyone (or any tool) reads the latest truth before the deep pages. - Plain text, local first, under version control. Markdown files in git: diffable, greppable, portable, no lock-in, readable without the app.
- Two stores, two names. This vault is the IPTV Obsidian Vault Wiki; the published, team-facing store is the ServiceNow IPTV Knowledge Base. Naming them apart stopped every "which KB?" question.
What is inside
| Area | Pages | What it holds |
|---|---|---|
| Systems | 118 | Every platform system, hubs with component and tool pages, the server map |
| CX Troubleshooting | 76 | 18 symptom decision trees, 21 anonymised case studies, flows, patterns, ticket taxonomy |
| How-tos | 22 | Step-by-step procedures, one per job |
| Network | 21 | IPTV path, BNG sessions, multicast and QoS, rate caps, edges |
| STB | 20 | Box models, firmware, boot, freezing deep dive, on-box commands |
| nPVR | 16 | Cloud recording end to end: booking, scheduler, recorder, storage, offload, quota |
| Home Network | 15 | Mesh Wi-Fi, routers, ONTs, GPON and XGS-PON |
| Vendors and People | 14 | Who supplies and decides what, and how to engage them |
| EPG | 13 | Guide structure, identifiers, feed, import job, guide versus picture |
| Decisions | 12 | 169 current rulings by topic, newest first |
| Incidents | 11 | 9 platform outages, each with cause and fix, plus the Outage Playbook |
| Logs | 10 | Log atlas, retention table, grep recipes, the client API call catalogue |
| Glossary | 10 | Hundreds of terms and acronyms (353 at the 2 Oct count), each pointing to its page |
| Projects | 10 | Wall, outage bot, baseline, remote box access, tunnel tool and more |
Twelve live database views (Obsidian Bases) sit on top: one per area, an Open Items view and a Wiki Freshness view that shows days since each page's update and its source count.
Fault-path maps
Four canvases turn the vault into maps: the IPTV Customer Path, and the fault paths for freezing, recordings (nPVR) and the guide (EPG). Each box is a real vault page; colour shows the layer or stage. In October 2026 I redrew them with straight right-angled links in lanes so a path reads left to right.
| Canvas | Boxes | Links |
|---|---|---|
| IPTV Customer Path | 118 | 84 |
| nPVR Fault Path | 297 | 280 |
| EPG Fault Path | 187 | 163 |
| Freeze Fault Path | 168 | 150 |
Staying true: the freshness check
A knowledge base is only useful while it is right. I wrote a read-only checker that runs weekly and reports three things: dead sources (a cited file moved or was removed), stale pages (a source changed more than 7 days after the page was last updated) and lint findings. It never edits a page; refreshing is a separate, reviewed step.
| Refresh round | Pages checked | Result |
|---|---|---|
| 2 Oct 2026 | 109 | Re-checked against the project; 57 dead sources repointed |
| 9 Oct 2026 | 114 | Two passes of 57 pages matched to project sources |
| 10 Oct 2026 | 58 | 22 changed, 36 verified; 0 stale, 0 dead |
| 19 Oct 2026 | 205 | 154 changed, 51 verified, 65 new decision rows, a new incident page; 0 stale, 0 dead, 0 lint |
Timeline
- 23 Sep 2026: vault set up; Systems, major nodes, Vendors and People, Incidents, How-tos, Decisions, Glossary, nPVR, EPG, Network, Home Network, STB and Logs written the same day.
- 24 to 27 Sep: recording symptom trees, the IPTV Customer Path canvas, the customer troubleshooting hub, gap passes on freezing, data stores and vendor facts.
- 2 Oct: Bases (freshness, per area, open items) and the Freeze, nPVR and EPG fault-path canvases; 109-page refresh.
- 9 to 10 Oct: two refresh rounds; ServiceNow capability map; the two-store naming ruling.
- 19 Oct: full refresh of 205 pages, canvases redrawn, monitoring-host GUI and provisioning pages; a cleaned snapshot shared with the senior director.
- Since: weekly freshness checks, updates as incidents and rulings land; 87 commits in all.
How it is used
- Every investigation starts here: the hot cache, then the page for the system or symptom in front of me, then its sources.
- The project's routing command points at the vault by name, so a lookup for "what is X" lands on the right page.
- Shared with leadership as a cleaned snapshot (no history, raw sources or personal area), as the platform's handover record.
- Feeds the published ServiceNow IPTV Knowledge Base: the vault is where facts are proven, the KB is where the team reads them.
The four roles in this project
- Engineer: every fact traced to logs, live reads or vendor documents; 21 real case studies and 9 incident write-ups.
- Designer: one page shape for every system, customer-first entry points, colour-coded maps that read left to right.
- System engineer: the whole platform modelled as layers and hops, from the TV to billing, with the links between them.
- Innovator: documentation that checks itself: source lists in the page, a weekly drift report, database views over the pages.
Numbers
| Pages | 373 in 13 areas |
| Words | about 677,000 |
| Cited project sources | 2,060 on 368 pages |
| Page-to-page links | 6,716 |
| Canvases | 4 (770 boxes, 677 links) |
| Database views | 12 |
| Decision rows | 169 |
| Commits | 87 since 23 Sep 2026 |