Learn

First Successful Document

A practical checklist for getting to a first clean Cuddler document without overcomplicating the first pass.

First pass

The shortest path to a first successful document

Keep the first iteration small enough to inspect, but complete enough to prove that the workflow works.

1Pick the right domain

Confirm which artifact family and governing domain you are actually working in.

2Draft compact data

Use a small example that is easy to validate and easy to review.

3Write the matching template

Keep the render contract aligned with that same data shape.

4Validate both

Treat passing validation as the gate before rendering.

5Render and inspect

Check that the output is understandable without manual cleanup.

The goal is a clean, understandable first success, not a large example.

A practical first pass

  1. Open the relevant Domain Specification and confirm which artifact family you are working in.
  2. Review the shared Artifact Specification so the authoring rules are clear before you start.
  3. Pick or draft a compact example of the data JSON you want to render.
  4. Write the matching template JSON with the same schema expectations.
  5. Validate the data, then validate the template.
  6. Render the document and check that the result matches the intent.

What success looks like

  • The document is small enough to inspect comfortably.
  • The data and template point to the same versioned contract family.
  • Validation passes before rendering begins.
  • The rendered output is understandable without extra cleanup.

Good first target

If you are unsure where to start, use an existing public surface as your reference point and keep the first version simple. You are trying to prove the workflow, not the final scale of the document.