Jason StedwellandClaude Opus 5.5
5b52636003
MPM Document Standard 1.3, mpmdoc build engine, templates for TN, INS, SOP, BOM, SVY, TAP, DWG, TSB, PRO, SOW and WO (Chinese editions for TN and DWG), glossary, MPM fonts and logos, and the mpm-technical-documents plugin 1.3.0. Worked examples ship in the kit zip on Drive only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NWatTMmqmGatgHjDZvWs5b
552 lines
36 KiB
Markdown
552 lines
36 KiB
Markdown
# MPM Document Standard
|
||
|
||
**Version 1.3 · Released · Nov 9, 2026 · Owner: Jason Stedwell**
|
||
|
||
This is the rule set for every technical document produced in the DOCUMENTATION PROJECT. It covers what each document type is for, how it is numbered, named and filed, how it looks, and how it reads. The engine in `mpmdoc/` enforces the mechanical parts (numbering, masthead, header/footer, palette, revision history); this document covers the judgement parts.
|
||
|
||
**MPM Documentation Kit edition.** Everything in the kit is Message Point Media. Replace your kit when MPM Technical Services releases a new version; the version line above tells you which one you have.
|
||
|
||
---
|
||
|
||
## 1. Document types
|
||
|
||
| Code | Type | Use it when | Audience | Default marking | Length | Template |
|
||
|---|---|---|---|---|---|---|
|
||
| **INS** | Installation Guide | Someone has to physically install hardware, step by step | Customer facilities, installers, MPM field | Customer | 4–10 pp | **Ready** · `templates/INS/` |
|
||
| **SOP** | Standard Operating Procedure | A repeatable internal task (setup, onboarding, process) | MPM staff | Internal | 2–6 pp | **Ready** · `templates/SOP/` |
|
||
| **TN** | Technical Note | One engineering question needs a worked, checkable answer | Customer + MPM engineering | Customer | 1–3 pp | **Ready** · `templates/TN/` |
|
||
| **BOM** | Bill of Materials | Pull, check and pack a set of parts | MPM shop / field | Internal | 1–2 pp | **Ready** · `templates/BOM/` |
|
||
| **SVY** | Site Survey | Recording what was found on site and what it means for design | Part 1 customer, Part 2 MPM-internal | Customer | 4–12 pp | **Ready** · `templates/SVY/` |
|
||
| **TAP** | Technical Action Plan | A planned engagement: scope, staffing, logistics, success criteria | Customer / OEM partner | Confidential | 5–12 pp | **Ready** · `templates/TAP/` |
|
||
| **DWG** | Drawing sheet (11×17) | Mechanical, cable, mounting or fit-out drawings with title block | Fabrication, customer approval | Customer | 1–4 sheets | **Ready** · `templates/DWG/` |
|
||
| **TSB** | Technical Service Bulletin | A known product issue and its fix for every affected unit | Customer edition: agencies, partners · Internal edition: MPM field and support | Customer (internal edition: Internal) | 2–5 pp | **Ready** · `templates/TSB/` |
|
||
| **PRO** | Proposal | Before award: need, proposed solution, why MPM, investment | Agency / partner decision makers | Confidential | 3–8 pp | **Ready** · `templates/PRO/` |
|
||
| **SOW** | Statement of Work | After award: contractual scope, deliverables, milestones | Customer / partner, under the MSA | Customer | 2–6 pp | **Ready** · `templates/SOW/` |
|
||
| **WO** | Field Work Order | Dispatching one job at one site to an MPM tech or a subcontract installer | Technician / installer, site contact | Internal | 1–3 pp | **Ready** · `templates/WO/` |
|
||
|
||
Also standard but not a PDF: **`00_INDEX.md`**, a project index (see §4.3).
|
||
|
||
New types are assessed when they come up; don't improvise a code. Add it to `brand.TYPES` and this table first.
|
||
|
||
**Picking the type:**
|
||
- Steps someone performs → INS (outside MPM) or SOP (inside MPM).
|
||
- A number, a fit or a yes/no with working → TN.
|
||
- A list of parts → BOM.
|
||
- A record of what exists on site → SVY.
|
||
- A plan for a visit or engagement → TAP.
|
||
- Geometry someone will fabricate from → DWG.
|
||
- A product defect and its fix across units → TSB. (One site's one-off problem is a TN or a TAP.)
|
||
- Winning the work → PRO. Defining the awarded work → SOW. A PRO never turns into the SOW; the SOW gets its own number.
|
||
- Sending someone to do one job → WO. How to do the job is the INS it references.
|
||
|
||
---
|
||
|
||
## 2. Brand selection
|
||
|
||
- **MPM** (gold/ink, Montserrat + Open Sans + JetBrains Mono) is used for every document.
|
||
|
||
---
|
||
|
||
## 3. Numbering
|
||
|
||
### 3.1 Format: `TYPE-CUST-SUBJ-NN`
|
||
|
||
| Field | Rule | Examples |
|
||
|---|---|---|
|
||
| TYPE | Code from §1 | `INS`, `TN`, `BOM` |
|
||
| CUST | 2–4 letters: customer code, or MPM department for internal docs (`IT`, `ENG`, `OPS`, `QA`), or `MPM` for company-wide/product docs | `LT`, `NSH`, `CMT`, `OMT`, `SOR`, `GIL` |
|
||
| SUBJ | 2–8 letters/digits naming the subject: site, product, bay, kit, job | `15R`, `B17`, `P25`, `HW`, `UNIFI`, `MON` |
|
||
| NN | Two-digit sequence within TYPE-CUST-SUBJ, starting `01` | `01`, `02` |
|
||
|
||
- Uppercase, hyphens only, no spaces.
|
||
- A number is issued once and never reused, even if the document is abandoned.
|
||
- A new subject on the same project gets a new SUBJ. A second document of the same type on the same subject gets the next NN.
|
||
- Register the customer code and the number in `registry.md` **before** the first build. The engine refuses unknown customer codes.
|
||
- TSB: `MPM` + product family for a product-wide bulletin (`TSB-MPM-LX270-01`); a customer code only when the issue belongs to one deployment.
|
||
- PRO / SOW: the customer the document is addressed to (the partner when MPM works through one, e.g. Vontas), SUBJ = project. A SOW that follows a PRO keeps the same SUBJ.
|
||
- WO: the customer code of the job, SUBJ = site or job; one WO per dispatch.
|
||
|
||
### 3.2 Existing documents
|
||
|
||
| Current | Standard number | Action |
|
||
|---|---|---|
|
||
| `INS-LT-15R-01` | same | Done: Rev 0.6 on engine |
|
||
| `SOP-IT-UNIFI-01` | same | Done: Rev 1.2 on engine; file renamed to its number |
|
||
| `TN-NSH-B17-01`, `TN-CMT-P25-01` | same | Done: Rev 0.3 on engine |
|
||
| `BOM-OMT-HW-01` | same | Done: Rev 0.2 on engine |
|
||
| `MPM-TAP-2606-001` Rev A / B | `TAP-GIL-M37-01` | Done: Rev A → 1.0, Rev B → 1.1, rebuilt as 1.2; old number listed under *Supersedes* |
|
||
| `MPM-TB-2604-001` (technical bulletin) | TBD | TB type not yet defined; assess when next needed |
|
||
| SORTA Monument Square survey Rev 0.1 (.docx) | `SVY-SOR-MON-01` | Done: rebuilt as PDF, Rev 0.2 |
|
||
| Power Whip Cable drawing (engineering, MWT) | TBD | Engineering-owned part drawings keep their part-number scheme; DWG numbers are for drawings produced in this project |
|
||
|
||
---
|
||
|
||
## 4. Revisions, files and folders
|
||
|
||
### 4.1 Revisions and status
|
||
|
||
- Revisions are numeric `MAJOR.MINOR` for every type, drawings included. Letter revisions (Rev A/B) belong to legacy and engineering part drawings only; when a lettered document is renumbered, issued letters map to 1.0, 1.1, … (Rev A → 1.0).
|
||
- **0.1, 0.2, …** are drafts. Status shows as `Draft` (red in the info strip).
|
||
- **1.0** is the first release. Anything given to a customer as final must be ≥ 1.0. Drafts may be shared but stay marked Draft.
|
||
- After release: **1.1, 1.2** for corrections and clarifications, **2.0** when the substance (scope, values, procedure) changes.
|
||
- Once a revision has been shared outside your machine, any change to the PDF bumps the revision, formatting-only changes included. An unshared draft may be rebuilt in place.
|
||
- **Revision history is mandatory.** One line per revision: what changed, not "updates". The engine prints it as its own block at the end of the document (§6).
|
||
- A document that replaces a different document number lists it under *Supersedes* (TAP, SVY).
|
||
|
||
### 4.2 File names
|
||
|
||
`{NUMBER}_{Customer}_{Short-Title}_Rev{X.Y}.pdf`
|
||
|
||
- Underscores separate fields; hyphens join words within a field. No spaces.
|
||
- Example: `TN-NSH-B17-01_Nashville_Bay17_Sign-Height-Change_Rev0.3.pdf`
|
||
- The engine builds this name from `slug="Nashville_Bay17_Sign-Height-Change"`.
|
||
- A Chinese edition adds `_ZH` before the revision: `DWG-NSH-STAR-01_WeGo-Star_LED-Banner_Mounting-Options_ZH_Rev0.2.pdf` (§12).
|
||
|
||
### 4.3 Folder layout
|
||
|
||
```
|
||
DOCUMENTATION PROJECT/
|
||
_ASSETS/ ← shared fonts and logos (mpm/): the only copies
|
||
_STANDARDS/ ← the standard, engine, templates, glossary, registry
|
||
_INPUTS/ ← reference material not tied to one project (outside drawings, examples)
|
||
<CUSTOMER> <PROJECT>/ ← one folder per project, e.g. "NASHVILLE BAY 17"
|
||
00_INDEX.md ← optional: status, contents, key numbers, owed items, sources
|
||
<current PDFs> ← latest revision of each document only
|
||
_superseded/ ← older revisions (moved here when a new rev is built)
|
||
_INPUTS/ ← what came in: site photos, screenshots, received drawings, quotes, field notes
|
||
source/ ← build.py, figs.py, img/ (prepared crops used in the PDF), _build/ (disposable)
|
||
```
|
||
|
||
- **The root holds folders only.** No PDFs, photos or loose files.
|
||
- **`_INPUTS/` holds originals and is never edited.** Crops and annotated versions used in a document go in `source/img/`.
|
||
- **Nothing is deleted from `_superseded/`.** It is the issued history.
|
||
- **"Claude outputs" is where the Claude app drops copies of files sent in chat.** Treat it as transient. The project folder holds the record.
|
||
|
||
**`00_INDEX.md` sections**, as in Nashville Bay 17:
|
||
- Status in one paragraph
|
||
- What's in this folder
|
||
- Key numbers
|
||
- What's still owed
|
||
- Could not open
|
||
- Source threads
|
||
|
||
---
|
||
|
||
## 5. Units, numbers, dates
|
||
|
||
- **Heights and clearances above grade:** feet-inches, `12'-10"`, to the nearest 1/16 (`units.ftin`).
|
||
- **Component and hardware dimensions:** use the units of the source drawing or part. Metric parts stay metric (`M8 × 1.25`, `107 × 465 mm`).
|
||
- **Customer-facing documents:** the first mention of a metric dimension gets the inch conversion: `312 mm (about 12-5/16 in.)`.
|
||
- **Characters:** use the true minus `−`, times `×`, diameter `Ø`, degree `°` and arrow `→`. Not `-`, `x` or `->`.
|
||
- **Numbers and units:** in the mono font in tables and calcs. Put a space between value and unit (`51.0 W`, `0.53 A`), except feet/inches and `%`.
|
||
- **Precision:** match the measurement; don't print 63.75 if you measured to ±0.1. One decimal for watts, two for amps.
|
||
- **Dates:** ISO in source (`2026-11-05`); displayed `Nov 5, 2026` everywhere in the document.
|
||
- **Unknowns:** use `TBC` (red) in a cell, never a guess. List each TBC as an open item.
|
||
|
||
---
|
||
|
||
## 6. Page anatomy
|
||
|
||
Every MPM document, top to bottom. The engine generates the items marked ⚙.
|
||
|
||
1. ⚙ **Running header (every page):** MPM logo left; document type (uppercase) and `NUMBER · REV X.Y` right; gold rule.
|
||
2. ⚙ **Kicker:** `Type · Customer · Subject` in gold small caps.
|
||
3. **Title (H1):**
|
||
- TN: name the thing being checked ("Bay 17 Sign: Mounting Height Change").
|
||
- INS/SOP: name the outcome ("15" Reflective Sign: Shelter Post Mount").
|
||
4. **Lede:** 2–3 sentences; the situation and what the document does.
|
||
5. ⚙ **Info strip:** five cells: Document · Revision · Date (*Effective* for SOP) plus **two type-specific cells** (§9).
|
||
6. **Opening:**
|
||
- TN: KPI tiles, then the dark *Result* box
|
||
- INS/SOP: dark *Before you start* box
|
||
- SVY: control table, dark *About this document* box, *Status of this revision* note
|
||
- TAP: document-control table and the confidentiality notice (no dark box)
|
||
- BOM: straight into the item tables
|
||
- TSB: compliance pill, applicability table, dark *Result* box
|
||
- PRO: parties, then KPI tiles (one `key` tile: the investment)
|
||
- SOW: the opening paragraph naming the parties, the MSA, the end customer and the quotation
|
||
- WO: status pill, parties (site · site contact · MPM dispatch), job table, *Safety* note
|
||
7. **Body:** sections with gold-ruled uppercase headings (`doc.section`). Figures and tables are numbered in order.
|
||
8. **Close:**
|
||
- TN: *Assumptions and open items*
|
||
- SVY: *To verify* list at the end of Part 2, then the appendices
|
||
- INS: *Final check*
|
||
- SOP: *Setup checklist*, *Troubleshooting*, *Need help?*
|
||
- BOM: *items to confirm* note and sign-off lines
|
||
- TAP: contacts, then the *Prepared and approved by* block
|
||
- TSB: *Compliance record*, then Part 2 in the internal edition
|
||
- PRO: *Next steps*, then a *Submitted by* block
|
||
- SOW: milestones, assumptions and exclusions, optional *Acceptance* signatures
|
||
- WO: *Completion record* and technician + site-contact signatures
|
||
9. ⚙ **Revision history block:** the last thing in every document, in its own cream block with a gold top rule. On the last page it sits at the **bottom** when it shares the page with content, or at the top when it lands on a page of its own.
|
||
10. ⚙ **Running footer (every page):** `MESSAGE POINT MEDIA · Born to Innovate. Built to Last.` left (tagline in Dark Gold, exactly as written); `CUSTOMER · SUBJECT [· INTERNAL USE | CONFIDENTIAL] · NUMBER · Page x of y` right. Override the context with `footer=` when it runs long; keep it under about 45 characters.
|
||
|
||
**Page setup:** US Letter portrait, margins 1.0 in. top, 0.7 in. bottom, 0.62 in. sides. DWG uses its own 11×17 landscape sheet (§9.7) instead of this anatomy.
|
||
|
||
**Page breaks:** start a new page (`new_page=True`) for a full-width figure page or a major part. Never leave a heading at the foot of a page. Headings are styled to stay with what follows, but check the PDF.
|
||
|
||
**Classification:**
|
||
- *Public / Customer*: no marking.
|
||
- *Internal*: footer says INTERNAL USE.
|
||
- *Confidential*: footer says CONFIDENTIAL, and page 1 carries a confidentiality notice naming the recipient and the governing NDA (TAP).
|
||
|
||
---
|
||
|
||
## 7. Visual system
|
||
|
||
### 7.1 Colour: each colour has one job
|
||
|
||
| Token | Hex | Job |
|
||
|---|---|---|
|
||
| Ink | `#232022` | Text, dark boxes, primary linework |
|
||
| Gold | `#DCBB4F` | Brand accent: rules, step numbers, header underline |
|
||
| Dark Gold | `#998643` | Kickers, labels, FIG/TABLE tags, centrelines |
|
||
| Light Accent | `#849698` | Ledes, captions, secondary text, running footer |
|
||
| Cream | `#F5F1EC` | Info strip, notes, calc blocks |
|
||
| Line | `#E6E0D8` | Table rules, figure frames |
|
||
| Key | `#FBF6E6` | The one highlighted row or tile |
|
||
| Red | `#A42D20` | Warnings, failing values, limits, minimums, Draft status |
|
||
| Green | `#3F6B3A` | PASS, passing values |
|
||
| Blue / Grey | `#2F5A8A` / `#B8B1A8` | Data series only, never UI |
|
||
|
||
Colours are the official MPM colour system (`_ASSETS/README.md`). Green PASS and the blue data series are functional additions, not brand colours, so keep them to status marks and data.
|
||
|
||
### 7.2 Type
|
||
|
||
- **Montserrat:** headings, kickers, labels, captions, table headers.
|
||
- **Open Sans 9.6 pt:** body. The brand's 11 pt applies to Word documents; dense technical PDFs stay at 9.6 pt (decided Nov 6, 2026).
|
||
- **JetBrains Mono:** numbers, dimensions, part numbers, calculations.
|
||
- All fonts come from `_ASSETS/mpm/fonts/` and are embedded in every PDF. Never substitute Arial, Calibri or a system font.
|
||
|
||
### 7.2a Logo
|
||
- Running header: `Logo-Gold-Black.png` (gold icon, dark text) on white.
|
||
- Dark title blocks: `Logo-Gold-White.png`.
|
||
- Drawings: the SVG equivalent.
|
||
- The full selection guide is in `_ASSETS/README.md`.
|
||
|
||
### 7.3 Components: use these, don't invent new ones
|
||
|
||
| Component | Engine call | Rules |
|
||
|---|---|---|
|
||
| Headline numbers | `doc.kpis()` | TN (and SVY summary): 3–4 tiles. Exactly one `key` tile (the answer); verdict tiles `ok`/`bad`. |
|
||
| Dark box | `doc.result()`, `doc.before_you_start()`, `doc.dark()` | Once per document, right after the info strip / KPIs. 2–6 bullets, key fact in bold. |
|
||
| Section | `doc.section()` | Short noun phrase. Uppercase is automatic. |
|
||
| Table | `doc.table()` | Header row is uppercase Montserrat with a **gold underline**, not the brand guide's dark header bar (decided Nov 6, 2026; reads better in dense numeric tables). Caption required if referenced. At most one `KeyRow`. Right-align numbers (`r`), mono for values (`m`, `d`). |
|
||
| Calculation | `doc.calc()` | Comment line, then `name = symbolic = numeric = result`. PASS/FAIL pill on the line that decides. |
|
||
| Figure | `doc.figure()` | Every drawn figure numbered and captioned; refer to it in text with `[[fig:key]]`. |
|
||
| Screenshot / photo | `doc.shot()`, `doc.shots()` | Files in `source/img/`. Captioned, **not numbered**, because each belongs to its step. Crop to the relevant part and mark the control to tap with a gold box. |
|
||
| On-screen control | `ui('Label')` | Any button, tile or link the reader taps, named exactly as it appears on screen. |
|
||
| Process at a glance | `doc.glance()` | INS/SOP. 4–8 tiles, two-word label + detail. A step done by someone else is a greyed ✓ tile. |
|
||
| Step | `doc.step()` | INS/SOP. A side figure keeps the step whole. `wide=True` puts the figure below; the text stays whole and only the figure may move to the next page. |
|
||
| Special case | `doc.special()` | SOP/INS. A gold-framed panel for a situation only some readers hit (e.g. outside the U.S.). At most one or two per document. |
|
||
| BOM table | `doc.bom()` | Line numbers continue across sections; subtotal row per section; Pulled/Packed checkboxes. |
|
||
| Note | `doc.note(kicker, body, tone)` | See §7.4. |
|
||
| Checklist | `doc.checklist()`, `doc.bullets(check=True)` | *Final check* (INS, two columns), *Setup checklist* (SOP, one column), open items. |
|
||
| Assumptions / open items | `doc.assumptions()` | TN and SVY close with this. Open items start with a verb. |
|
||
| Sign-off | `doc.signoff()`, `doc.approval()` | Sign lines (BOM); *Prepared and approved by* block (TAP). |
|
||
| Control table | `doc.kv()` | Front matter of SVY and TAP: label / value rows (prepared for, supersedes, distribution …). |
|
||
| Part divider | `doc.part()` | SVY Part 1 / Part 2 / Appendices. `internal=True` marks an MPM-internal part. |
|
||
| Site photo | `doc.photo()`, `doc.photos()` | Numbered FIG, two side by side, max 2.7 in. tall. Every photo also appears in the photo log. |
|
||
| To-verify tag | `verify()` | Inline red tag on a point of record to confirm with the customer; each one also listed in the *To verify* note. |
|
||
| Field notes | `doc.transcript()` | Verbatim notebook transcription: spelling preserved, editorial text in [brackets]. |
|
||
| Drawing sheet | `Drawing(...)`, `dwg.view()`, `dwg.sheet()` | DWG only (§9.7). |
|
||
| Priced BOM | `doc.priced()` | PRO / SOW. SKU · description · qty · extended price, subtotal per group, grand total. Prices are numbers from the quotation; totals are computed (`doc.price_total`), never typed. |
|
||
| Milestones | `doc.milestones(rows, expect=doc.price_total)` | SOW (and PRO payment terms). The build fails if the milestones don't add up to the priced total. |
|
||
| Parties | `doc.parties()` | PRO / WO (SOW names them in the opening paragraph). MPM's block is `brand.PROVIDER`. |
|
||
| Status / compliance pill | `doc.pill(text, colour)` | TSB compliance: Mandatory `red` · Recommended `gold` · Informational `grey`. WO status: Dispatched `gold` · On site `ink` · Complete `green` · On hold `red`. One per document. |
|
||
| Fill-in record | `doc.fields()`, `doc.table(..., cls="fill")` | WO completion record; TSB compliance record (blank ruled rows). |
|
||
| Signatures | `doc.signatures([(role, who)])` | WO (technician + site contact); SOW *Acceptance* when the customer signs the SOW itself. |
|
||
|
||
### 7.4 Note kickers (fixed vocabulary)
|
||
|
||
| Tone | Kickers |
|
||
|---|---|
|
||
| `info` (cream/gold) | GOOD TO KNOW · CHECK · CHECK YOUR MARKS · TWO WAYS TO … · ON ANDROID · NEED HELP? · STATUS OF THIS REVISION · WHAT CHANGED IN THIS REVISION · *topic-specific short label* |
|
||
| `warn` (red) | WARNING · LINE VOLTAGE · CHECK POLARITY · WATCH FOR … · DON'T … · DRAFT · ITEMS TO CONFIRM BEFORE RELEASE · PROPRIETARY & CONFIDENTIAL |
|
||
| `ok` (green) | CONFIRMED · RESOLVED · CLOSED |
|
||
| `verify` (dashed) | TO VERIFY WITH {CUSTOMER} BEFORE RELEASE: points of record still to confirm (SVY) |
|
||
|
||
*Action required* (TAP) uses `doc.special()`, not a note.
|
||
|
||
- Use a warn note only when getting it wrong can hurt someone or damage equipment.
|
||
- At most one warn note per step.
|
||
|
||
---
|
||
|
||
## 8. Writing
|
||
|
||
**Voice:**
|
||
- Plain, direct, specific.
|
||
- Short sentences.
|
||
- Active voice.
|
||
- No marketing language in technical documents.
|
||
|
||
**Answer first:**
|
||
- A TN's Result box must stand on its own.
|
||
- A reader who stops after the Result should have the right answer and its conditions.
|
||
|
||
**Procedures (INS/SOP):**
|
||
- Each step starts with a verb: *Mark the hole locations*. One step is one outcome.
|
||
- Numbered sub-steps: 3–6, one action each.
|
||
- Bold the object or value the reader must get right: **plumb**, **1/2 in. cobalt**, **breaker off**.
|
||
- The step kicker names the tool, part or place for that step: `Ø1/2 IN. COBALT BIT`, `UNIFI ENDPOINT`.
|
||
- Every step that changes something physical gets a figure.
|
||
- Say what success looks like: a CHECK note, or a closing *Final check* list.
|
||
|
||
**Numbers:**
|
||
- Every number traces to a measurement, a document or a calculation shown in the document.
|
||
- Keep source numbers in one place (`figs.py`) and derive the rest in code. Never retype a derived value.
|
||
|
||
**Names:** use the customer's name for itself on first use in the kicker or lede (*Nashville MCC (WeGo)*, *SORTA / Metro*); short form after that.
|
||
|
||
**Unknowns:**
|
||
- `TBC` in tables.
|
||
- *Open items* in TN/SVY.
|
||
- *Draft · items to confirm* warn note on BOM.
|
||
- Never paper over an unknown.
|
||
|
||
**Attribution:** when a requirement came from a person or email, the source is recorded in `00_INDEX.md`, not in the customer document.
|
||
|
||
### 8.1 MPM brand voice in technical documents
|
||
|
||
Technical documents sit at the **high formality · low energy · very high technical depth** end of the MPM tone matrix (hardware/maintenance documentation). The MPM voice still applies:
|
||
|
||
- **Expert partner, not vendor.** Explain the why behind a step or a limit. Don't lecture and don't sell.
|
||
- **Precise and purposeful.** Exact names and numbers. No superlatives ("cutting-edge", "best-in-class", "revolutionary").
|
||
- **Riders and passengers, not users,** when the end audience is the public. Use **transit agencies / agencies** for customers in transit contexts.
|
||
- **Accessibility is a design principle, not a checkbox.** State ADA requirements as what makes the sign work for riders (reach range, audio), never as a compliance burden.
|
||
- **Own the complexity.** When something is hard, say so, then show the way through it. Proactive wording ("preventative check") rather than firefighting.
|
||
- **Terminology:**
|
||
- *native* API integration (never wrapper or middleware)
|
||
- *MP.TV CMS* in customer-facing documents
|
||
- *RDMC*
|
||
- *GTFS-RT*
|
||
- *publishing rules*
|
||
- hardware product names exactly as in the brand settings (e.g. *MR Series*, *MR27*)
|
||
- **No conference-theme language** (MPower motorsports metaphors) in documents.
|
||
|
||
Brand source: the mpm-brand-voice plugin (`settings/brand-voice.local.md`).
|
||
|
||
---
|
||
|
||
## 9. Per-type specifications
|
||
|
||
The two type-specific info-strip cells and the required section order for each type. Every type has an engine template in `templates/<TYPE>/` with a preview PDF.
|
||
|
||
### 9.1 INS: Installation Guide *(ready: `templates/INS/`)*
|
||
- **Info cells:** Audience · Mount/Install type
|
||
- **Sections:**
|
||
1. Before you start (dark box)
|
||
2. Process at a glance (4–8 tiles)
|
||
3. Hardware table + Tools table, side by side, kept together as one block
|
||
4. Reference figure (template / drill schedule) if needed
|
||
5. Walkthrough (numbered steps with figures)
|
||
6. Final check (two-column checklist; last item "Photo of the finished install sent to MPM")
|
||
|
||
### 9.2 SOP: Standard Operating Procedure *(ready: `templates/SOP/`)*
|
||
- **Info cells:** Audience · Time needed
|
||
- **Sections:**
|
||
1. Before you start
|
||
2. Process at a glance (tiles labelled with who does it: IT / YOU)
|
||
3. Walkthrough (numbered steps, screenshots as side figures)
|
||
4. Special cases (e.g. *Outside the U.S.*), placed after the step they relate to
|
||
5. Setup checklist (one column)
|
||
6. Troubleshooting table (Problem · What to do)
|
||
7. *Need help?* note
|
||
- Marked INTERNAL USE.
|
||
|
||
### 9.3 TN: Technical Note *(ready: `templates/TN/`)*
|
||
- **Info cells:** context (Site / Measured / Module) · criterion (Requirement / Deployment)
|
||
- **Sections:**
|
||
1. KPI tiles (3–4)
|
||
2. Result
|
||
3. Evidence: comparison table → calculation → figures
|
||
4. Assumptions and open items
|
||
- 1–3 pages. If it needs more, it is probably two notes or a report.
|
||
|
||
### 9.4 BOM: Bill of Materials *(ready: `templates/BOM/`)*
|
||
- **Info cells:** Customer · Prepared by
|
||
- **Columns:** # · Item · Specification · Qty · UOM · Part no. · Pulled · Packed
|
||
- **Grouping:** by category (Fasteners, Sealing & consumables, …), each with a subtotal row.
|
||
- **Close:** *Draft · items to confirm before release* warn note while < 1.0, then sign-off (Pulled by · Checked by · Date).
|
||
|
||
### 9.5 SVY: Site Survey *(ready: `templates/SVY/`)*
|
||
- **Info cells:** Survey date · Surveyor
|
||
- **Front matter:**
|
||
- Prepared for / by
|
||
- Basis (notes, photos, drawings received)
|
||
- About this document
|
||
- **Part 1, Summary of Findings (customer):**
|
||
- Purpose
|
||
- Scope
|
||
- What we found (table by stop or family)
|
||
- What it means
|
||
- **Part 2, Engineering Detail (MPM-internal):**
|
||
- Survey record
|
||
- Inventory
|
||
- One section per mount family (observations → design constraints)
|
||
- Power & data
|
||
- TO VERIFY list
|
||
- **Appendices:** A, photo log (# · time · cluster · file ID · subject, citing the figure numbers); B, verbatim field-notes transcription with the notebook pages.
|
||
- **Release to the customer:** the PDF is marked INTERNAL USE while it carries Part 2. Release Part 1 + appendices as a customer edition (to be added to the engine when the first survey is released).
|
||
|
||
### 9.6 TAP: Technical Action Plan *(ready: `templates/TAP/`)*
|
||
- **Info cells:** Customer · Engagement dates
|
||
- **Front matter:**
|
||
- Document-control table: Supersedes / References · Distribution · Affected products · Personnel · Site
|
||
- Confidentiality notice
|
||
- **Sections** (numbered in the heading text):
|
||
1. Purpose and scope (with *What changed in this revision* from 1.1 on)
|
||
2. Background: known-issue register and failure groups
|
||
3. Information required from the customer (*Action required* panel)
|
||
4. Personnel: field technician, coordination, oversight
|
||
5. Parts and equipment kit
|
||
6. Timeline and daily schedule
|
||
7. Procedures by failure group, then disposition
|
||
8. Open items and decisions
|
||
9. Acceptance criteria (per unit, engagement)
|
||
10. Daily reporting
|
||
11. Escalation and contacts
|
||
- **Close:** *Prepared and approved by* block.
|
||
|
||
### 9.7 DWG: Drawing sheet *(ready: `templates/DWG/`)*
|
||
- **Sheet:** 11×17 landscape, zone grid (8–1 across, D–A down), header bar with logo, discipline and `DWG NO · SHEET · REV`.
|
||
- **View area:** a 6 × 4 grid. Each view has a numbered bubble, a title and a scale.
|
||
- **Right column, top to bottom:**
|
||
- Schedule: tag · designation · description · qty, with tags as gold bubbles that match the callouts on the views
|
||
- General notes, numbered
|
||
- Title block: project, title, client, location, scale, drawn / checked / approved, dwg no., sheet n of N, rev, date
|
||
- Revision history
|
||
- Confidentiality strip with the tagline
|
||
- **Drafting conventions:**
|
||
- Ink linework; centrelines Dark Gold, long-dash-dot; hidden lines dashed
|
||
- Dimensions in mm (JetBrains Mono) with extension lines
|
||
- "Do not scale from drawing" in the general notes
|
||
- **Revisions:** numeric like every other type (§4.1). Multi-sheet sets share one number and revision.
|
||
|
||
### 9.8 TSB: Technical Service Bulletin *(ready: `templates/TSB/`)*
|
||
- **Info cells:** Compliance · Effective
|
||
- **Two editions from one `build.py`:**
|
||
- Customer edition: classification customer; slug ends `_TSB`.
|
||
- Internal edition: classification internal; slug ends `_TSB-Internal`; adds Part 2 *Diagnostic detail* (root cause, field data, support notes).
|
||
- Same number, same revision, issued together. The customer edition never contains Part 2.
|
||
- **Front:** compliance pill; applicability table (Applies to · Affected units · Not affected · Labor estimate · Supersedes · Distribution); dark *Result* box (what happens, what to do, by when).
|
||
- **Sections:** 1 Symptom · 2 Cause · 3 Corrective action (steps; reference an INS for anything long) · 4 Verification · 5 Parts.
|
||
- **Close:** *Compliance record*, a blank table (unit serial, site, date, technician, done) the field fills in.
|
||
- **Compliance levels:** Mandatory (failure or safety; fix by a stated date) · Recommended (fix at the next visit) · Informational (no action).
|
||
|
||
### 9.9 PRO: Proposal *(ready: `templates/PRO/`)*
|
||
- **Info cells:** Prepared for · Valid until
|
||
- **Front:** parties (Prepared for · Prepared by = `brand.PROVIDER`); KPI tiles with the investment as the one `key` tile.
|
||
- **Sections** (numbered in the heading text): 1 Your situation · 2 Proposed solution · 3 Why Message Point Media · 4 Scope summary (phase · MPM provides · agency provides) · 5 Investment (`doc.priced`, with a *Pricing* note naming the quotation and validity) · 6 Timeline · 7 Assumptions and exclusions · 8 Next steps.
|
||
- **Close:** *Submitted by* block (`doc.approval(..., label="Submitted by")`).
|
||
- **Rules:** every price comes from a quotation; §3 holds facts you can back up (deployments, agencies, years, uptime), never superlatives. Marked CONFIDENTIAL. After award, write the SOW; don't revise the PRO into one.
|
||
|
||
### 9.10 SOW: Statement of Work *(ready: `templates/SOW/`)*
|
||
- **Info cells:** Customer · Quotation
|
||
- **Opening paragraph:** made by and between Customer and Message Point Media of Alabama, Inc (MPM); subject to the Master Services Agreement; for the benefit of the End Customer; pricing per Quotation S#####, its date and expiry.
|
||
- **Sections** (numbered `1.0`, `2.1`, `2.1.1` in the heading text):
|
||
1. 1.0 Scope overview (say what is *not* included when a reader might assume it is)
|
||
2. 2.0 Project deliverables: 2.1 Hardware (list, then 2.1.1 priced BOM per the quotation) · 2.2 Documentation (document · purpose)
|
||
3. 3.0 Scope of work: 3.1 Initiation and scheduling · 3.2 Site confirmation · 3.3 Procurement and provisioning · 3.4 Delivery · 3.5 Installation · 3.6 Operational verification · 3.7 Warranty (name the warranty policy)
|
||
4. 4.0 Project milestones (`doc.milestones(..., expect=doc.price_total)`)
|
||
5. 5.0 Assumptions and exclusions
|
||
6. 6.0 Acceptance: signatures, only when the customer signs the SOW itself
|
||
- **Revisions:** 0.x while negotiating; 1.0 = executed. Reference: `SOW_Nashville_Replacement_Sign_S01012` (Aug 2026), in `NASHVILLE BAY 17/_INPUTS/04_Commercial/`.
|
||
|
||
### 9.11 WO: Field Work Order *(ready: `templates/WO/`)*
|
||
- **Info cells:** Scheduled · Assigned to
|
||
- **Front:** status pill; parties (Site with coordinates · Site contact · MPM dispatch); job table (Customer / project · Installer · Access · Reference documents); *Safety* note.
|
||
- **Sections:** Work to be performed (checkboxes, each an action) · Parts and materials (`doc.bom`, Staged / Used checks) · Return with this work order (photos, serials, measured deviations).
|
||
- **Close:** *Completion record* (`doc.fields`: arrival, departure, serials installed and removed, online on MP.TV, issues) and technician + site-contact signatures.
|
||
- **Rules:** marked INTERNAL USE (contacts, access). Issued at 1.0; a re-dispatch with a changed scope or date is 1.1. The signed paper copy is scanned into the project's `_INPUTS/` and never edited; the PDF stays as issued. The how-to lives in the referenced INS, not in the WO.
|
||
|
||
---
|
||
|
||
## 10. Before you issue (checklist)
|
||
|
||
- [ ] Number registered in `registry.md`; file name matches §4.2
|
||
- [ ] Revision bumped; history line says what changed
|
||
- [ ] Result / Before-you-start box stands on its own
|
||
- [ ] Every figure and table numbered, captioned and referred to in the text
|
||
- [ ] Every number traceable; no retyped derived values; TBCs listed as open items
|
||
- [ ] Units and characters per §5 (− × Ø °)
|
||
- [ ] Classification correct; confidential documents carry the NDA notice
|
||
- [ ] PRO / SOW: prices match the quotation line for line; milestones add up (the build checks); validity date set
|
||
- [ ] TSB: customer edition opened and checked to contain no Part 2
|
||
- [ ] Opened the PDF and looked at every page: no orphan headings, no clipped figures, no stray near-empty last page
|
||
- [ ] Previous revision moved to `_superseded/`
|
||
- [ ] Chinese edition (if any) rebuilt at the same revision, its previous revision also moved to `_superseded/`
|
||
|
||
---
|
||
|
||
## 11. Asking Claude for a document
|
||
|
||
Say the type and the subject; Claude reads this standard and the template:
|
||
|
||
> "TN for CommTran: per-sign power roll-up for the 4×2 Pingo layout"
|
||
> "Rev the Nashville TN — hanging hardware is 2 in. taller than the old"
|
||
> "INS for LakeTran: 15-inch sign on a round pole"
|
||
|
||
Claude asks for the number you claimed in the shared registry, builds in `<PROJECT>/source/` with `mpmdoc`, and puts the PDF in the project folder. Anything it can't source becomes a TBC or an open item, never a guess.
|
||
|
||
**How builds run:**
|
||
- Claude needs your kit folder: open it in the Claude desktop app (or link the computer that holds it), and install the **mpm-technical-documents** plugin from `_PLUGIN/`.
|
||
- Builds need Python 3.10+ with Playwright/Chromium and poppler. Run `setup.sh` once (see `START_HERE.md`); then `python3 build.py` in a project's `source/` folder builds the PDF. When Claude can't run Python on your computer, it builds in its cloud workspace and writes the PDF back to your folder.
|
||
|
||
**Numbers are claimed in the shared registry.** The `registry.md` in your kit is a snapshot. The master registry is kept in one shared place set by MPM Technical Services: claim a number there before your first build, then copy the row into your own `registry.md`. A number is never reused, even for an abandoned draft.
|
||
|
||
**Keeping documents.** Issued PDFs go to the shared project location for the job, together with their `source/` folder, so the next revision starts from the same source.
|
||
|
||
The **mpm-technical-documents** plugin carries this workflow, so any Claude session follows it.
|
||
|
||
---
|
||
|
||
## 12. Chinese editions (简体中文) for manufacturers
|
||
|
||
For drawings and technical notes going to a Chinese manufacturer, MPM issues a **Chinese edition** alongside the English one.
|
||
|
||
**Scope.** TN and DWG only (`mpmdoc.i18n.TYPES`). Other types are assessed when needed.
|
||
|
||
**What it is.**
|
||
- A second PDF of the same document: same number, slug, revision, figures and geometry.
|
||
- Body text is in Simplified Chinese.
|
||
- Frame labels are bilingual (`图号 Dwg no.`, `部件表 · Schedule`), so MPM staff can find their way around it.
|
||
- File name: `{NUMBER}_{slug}_ZH_Rev{X.Y}.pdf`, kept in the project folder next to the English edition.
|
||
- **The English edition governs.** Every Chinese edition says so:
|
||
- TN: a line under the masthead.
|
||
- DWG: a general note on every sheet.
|
||
- The engine adds the statement automatically unless a note already carries it.
|
||
- Revisions move together: a new English revision means a new Chinese edition at the same revision. The history lines are translated; the revision numbers and dates are identical.
|
||
|
||
**How it's built.**
|
||
- `source/build_zh.py` sits next to the English `build.py`; start from `templates/TN/build_zh.py` or `templates/DWG/build_zh.py`. It shares `figs.py` with the English build and passes `lang="zh"` to `Doc` / `Drawing`.
|
||
- Build the English edition first. The engine refuses to build a Chinese edition unless the English PDF at the same revision is already in the project folder.
|
||
- Write the Chinese strings in the same order as `build.py`, so the two files can be compared side by side.
|
||
- **Figure text:** goes through `i18n.Translator`.
|
||
- Lookup order: the document's own `TERMS` table, then the master glossary `_STANDARDS/glossary_zh.md`.
|
||
- `tr.check()` fails the build on any English left in a figure.
|
||
- Numbers with units, tags (`S-1`, `M3`), part numbers and standards pass through unchanged.
|
||
- **Terms:** one English term, one Chinese term.
|
||
- A term that will recur goes in `glossary_zh.md`; a sentence specific to one document goes in its `TERMS`.
|
||
- When a manufacturer corrects a term, change the glossary and rebuild the Chinese editions that use it.
|
||
- **Units:** mm first, imperial in [ ]; mass in kg, with lb in [ ] where the source is lb. If `figs.py` formats dimensions through a function `F`, `build_zh.py` replaces it before drawing the figures.
|
||
- **Keep in Latin script:** part and model numbers, tags, units, standards (ADA 307, IP66, UL 48), place and station names, brand names, the tagline.
|
||
- **Dates:** shown as `2026年11月9日`.
|
||
|
||
**Font.**
|
||
- Chinese text is set in **MPM SC**: Noto Sans CJK SC (SIL OFL), cut to GB2312 and converted to TrueType in `_ASSETS/mpm/fonts/cjk/` by `make_cjk.py`.
|
||
- The engine embeds only the characters each document uses, and adds MPM SC as the fallback to every font stack. Latin text and numbers stay in Montserrat / Open Sans / JetBrains Mono.
|
||
- No system font is used, so a build looks the same on any machine.
|
||
|
||
---
|
||
|
||
## Standard revision history
|
||
|
||
| Version | Date | Change |
|
||
|---|---|---|
|
||
| 1.3 | Nov 9, 2026 | Chinese editions for TN and DWG (§12): `lang="zh"` in the engine, MPM SC font, master glossary `glossary_zh.md`, `build_zh.py` templates; `_ZH` file names (§4.2); checklist line (§10). |
|
||
| 1.2 | Nov 6, 2026 | Added TSB, PRO, SOW and WO (§1, §3.1, §6, §7.3, §9.8–9.11, §10) with templates; new components `priced`, `milestones`, `fields`; MPM styling for parties, pills and signatures. |
|
||
| 1.1 | Nov 6, 2026 | Brand references updated. |
|
||
| 1.0 | Nov 6, 2026 | Released. MPM document types TN, INS, SOP, BOM, SVY, TAP and DWG with engine templates; shared `_ASSETS`; folder layout with `_superseded/` and `_INPUTS/`. |
|