Authoring Guide

This guide focuses on writing maintainable ProtoML documents, not on listing every syntax rule.

Start with a consistent skeleton

document metadata
participants
subjects
tags or tag imports
tasks
meeting content
optional governance blocks such as signatures, approvals, references, or attachments

This order keeps the structural source of truth near the top and the human-readable narrative near the bottom, which makes large files easier to review and diff.

Name things for reuse

Prefer stable, meaningful IDs such as lead, pm, security, release, or review.

A good rule is that an ID should still make sense three months later without reading the whole file again.

Keep structured data in blocks

If a value should be reused later, define it once in a block instead of duplicating it in prose.

Participants belong in @participants, not copied repeatedly in meeting text
Use @participants_import when multiple documents share the same participant roster
Subjects belong in @subjects, then tasks and notes can point back to them
Approval and signature data belong in their dedicated blocks if they are referenced more than once

Use shared tags for teams and projects

Move stable task vocabularies into shared _tags.pml files when multiple documents share the same workflow or cross-file analysis matters.

Keep local tags only when a label is temporary, one-off, or too project-specific to be worth sharing.

Split large documents deliberately

Use @import for appendices, reusable legal or policy text, standard meeting sections, or shared snippets.

The main document should still read like the table of contents and orchestration layer of the whole document, not like a random pile of imports.

Use macros sparingly but intentionally

Macros are best for repeated presentation patterns such as alerts, badges, summaries, timelines, and finance cards.

If the repeated thing is really content, choose imports. If you need a reusable rendered component with its own structure and presentation, choose macros. If you only want to change the overall document look, choose a renderer theme instead.

Governance documents need extra discipline

Establish conventions for @record_id, @status, @author, @version, @effective_date, @valid_until, and @review_date, then use protoparser register "<dir>" statistics.

Worked example

@tags_import "_workflow_tags.pml"
@protocol "Platform Weekly Sync - {{date}}"
@date:17.04.2026
@author:Jane Doe
@status:review
@record_id:PLATFORM-WEEKLY-2026-04-17

@participants
=lead:Jane Doe,jdoe,jdoe@example.com
=ops:Max Mustermann,mmustermann,max@example.com
=sec:Alex Roe,aroe,alex@example.com

@subjects
=release:Release status
=security:Security review
=followup:Next actions

@tasks
-[ ] Finalize release notes @ptp=lead =release @tag=important
-[ ] Recheck deployment window @ptp=ops =release @tag=review
-[ ] Confirm exception handling for audit finding @ptp=sec =security @tag=blocked

@meeting "Weekly Minutes"
# Platform Weekly Sync
## Summary
Current focus: @@e=release
## Participants
@@e=lead, @@e=ops, @@e=sec
## Open points
Audit topic: @@e=security
Next section: @@e=followup

Why this example is maintainable

Document identity and lifecycle are visible at the top
Participant and subject IDs are stable and descriptive
Tasks point to structured subjects and tags instead of embedding everything in plain text
The meeting block reads clearly while still reusing structured values
The shared tags file keeps workflow classification consistent across multiple documents

Common authoring mistakes

Using throwaway IDs such as 1 or x for everything
Keeping important document metadata only in prose
Copying repeated names and labels instead of referencing them
Using macros where a plain import or structured block would be simpler
Letting large files grow without extracting reusable imported sections