Most port documentation fails for a boring reason: it is unstructured prose about structured things. A dock is a graph. It has a deck, a piling field, a berth line, a utility run, a dredge cycle, a lease boundary, and an inspection schedule, all with relations between them. Storing that as a PDF throws the graph away and leaves you re-deriving it by hand every quarter.
Shapezo's answer is to model the asset first and render prose second. Content becomes typed objects with a schema, and the article is a build artifact. This post walks through the model and the pipeline.
The dock schema
Two fields deserve attention because they are the Shapezo-specific part. narrative.shape selects the article structure from a fixed enum (tide_cycle, cargo_journey, negotiation, service_record). anchor_details names the one or two physical details the prose is allowed to go deep on. Everything else stays at summary depth. That single constraint is what keeps generated articles readable.
Rendering prose from the model
The renderer is a template per narrative shape. Each template is a sequence of sections with slots bound to schema paths. Nothing free-form: if a slot has no data, the section renders a visible TODO marker rather than silently vanishing, so gaps surface in review instead of in production.
Because the output is deterministic for a given schema, diffs are meaningful. A schema change shows up as a clean article diff in code review, which is exactly where infrastructure knowledge changes should be reviewed.
The weight target matters more than it sounds. Dock guides get read on tablets at the water's edge, on cellular links, often in ports where coverage is poor precisely because the structure blocks it. A 200KB budget per image keeps a full three-scene guide under a megabyte.
The aerial berth survey below is a good example of a context asset: one oblique frame captures slip geometry, quay line, and warehouse relation that would take six ground photographs to convey.
Why the shed interior is the load-bearing shot
Of the three slots, hardware is the one that pays for the pipeline, and for covered docks the pier shed interior is its best expression. Truss condition, clerestory glazing, floor wear, and cargo layout all change on a quarterly cycle, so the interior image doubles as a condition baseline. Keeping it in the schema means the comparison is a git diff of images at a fixed viewpoint, not an archaeology project.
What you get
Model first, render second, and three things change. Documentation becomes reviewable, because schema changes produce article diffs. It becomes complete, because empty required slots fail loudly. And it becomes cheap, because updating a dock is editing four YAML blocks instead of rewriting prose.
Shapezo is not a CMS and not a static site generator. It is the discipline of deciding the shape of your content before you write it, plus just enough tooling to enforce that decision. For waterfronts, where the underlying asset is already a well-defined graph, that discipline is almost unfair leverage.
Top comments (0)