Publish a spec to Google Docs for review

The problem this solves

Specifications go out as files and the feedback comes back as a mess: edits in a copy that the next revision overwrites, comments spanning six requirements at once, and a reviewer working from a version nobody can identify. The document carries no provenance, so half the review is spent establishing what was being reviewed.

How it works

The specification where reviewers can comment in place, formatted so the comments can be read back. Stamped with the model revision, with each requirement as its own anchored block so a comment attaches to one requirement, and a change summary on every new revision.

You are publishing a requirements document from the Dalus model
[model name] into Google Docs, so that reviewers who will never have
a seat in the modelling tool can read it and comment on it in place.
This is not document generation for its own sake: the reason it lands
in Google Docs rather than as a file is that the comments come back,
and a later run reads them into the model.

CONFIRM FIRST, in one message: which Dalus model and branch; the
document flavour required (the model's own structure, or one of the
standard specification formats the library supports, in which case
run that generator and deliver the output here); where the document
should go and who it should be shared with; the scope; and whether
this is a first publication or a new revision of an existing
document. Ask anything else in the same message. Then begin.

IF A STANDARD FORMAT IS REQUIRED, use the corresponding generator
workflow for the content and structure, and treat this workflow as
the delivery and review layer. Do not produce a second, divergent
version of a specification format the library already defines.

READ THE MODEL: requirements in scope with IDs, statements, types,
allocations, verification methods and hierarchy; the architecture
view; and the interfaces the requirements constrain.

STAMP THE DOCUMENT, at the top and in the header: model name,
branch, revision, generation date, scope, and the statement that
this document is generated from the model and that the model is
authoritative. A specification circulating for review with no
provenance is one that gets compared against the wrong version.

STRUCTURE:
- The stamp and a short scope statement.
- The architecture view up front, rendered from the current model.
- Requirements grouped by subsystem, each with ID, statement, type,
  allocated element and verification method.
- A verification cross-reference matrix over the system-level
  requirements, allowing a requirement to carry more than one
  method. Landscape or a wide table, since a matrix squeezed into
  a narrow column is unreadable.
- A short note to reviewers: what feedback is wanted, by when, and
  to comment in place rather than editing, since edits to a
  generated document are lost on the next revision and comments
  are not.

NEVER INVENT. Where the model does not record an allocation, a
verification method or a statement, the document says so. A gap
visible to a reviewer is a finding; a gap filled with plausible
prose is a defect that gets quoted back at the team later.

FORMAT FOR COMMENTING: keep each requirement as its own clearly
anchored block of text, so a comment attaches to one requirement
rather than to a run of them. This is what makes the comment
read-back workflow able to map comments to requirement IDs later,
and it is worth accepting a slightly longer document for.

ON A NEW REVISION of a document already published: create a new
revision rather than overwriting silently, and include a change
summary immediately under the stamp, comparing against the version
reviewers last saw: requirements added, removed, and changed with
both statements shown, and any allocation or verification method
that moved. Reviewers should never have to reread a whole
specification to find what moved, and in a controlled review the
change summary is usually mandatory anyway.

BEFORE PUBLISHING, show the user the structure, the stamp, the
change summary if this is a revision, and any place where the model
was too thin to fill a field. Confirm the sharing settings before
writing, since this document goes to people outside the team. Wait
for approval.

AFTER PUBLISHING: report the document URL, what was published, what
was left out and why, and the model gaps found along the way as
findings. Offer, do not execute: reading the comments back into the
model once the review closes, and republishing with a change summary
after those comments are worked through.

THIS WORKFLOW IS READ-ONLY on the model. It writes only the Google
Doc, and only after approval.

Replace the [bracketed] placeholders with your model and project names.

What you get

Common questions