nejimakibird_model-weave/docs/V0.8-documentation-policy.md

Model Weave V0.8 Documentation Policy

Japanese Version: 日本語版

Purpose

This document defines the V0.8 documentation policy for Model Weave.

V0.8 defines the current rendering policy for Custom / Mermaid rendering and render_mode. V0.8 defines how Model Weave documentation, especially FORMAT specifications, should be structured and maintained.

The goal is to make Model Weave documentation easier to use for:

• first-time users
• maintainers
• AI assistants generating Model Weave Markdown
• reviewers checking generated models
• users rebuilding design documents from source code and specifications

This policy is about documentation structure. It does not change plugin behavior, parser behavior, renderer behavior, or model file compatibility.

Documentation policy version and plugin version

The documentation policy version and the plugin version are separate concepts.

For example:

• Plugin version: 0.1.x
• Rendering policy: V0.8
• Documentation / FORMAT policy: V0.8

V0.8 in this document means the documentation policy version. It does not mean that every feature described here belongs to plugin version 0.8.

Documentation roles

Model Weave documentation is divided by role.

README

The root README.md is the landing page.

It should explain:

• what Model Weave is
• what it is used for
• how to start using it
• which commands to try first
• where to find detailed documentation

The README should not contain every command or every FORMAT detail.

Getting Started

The Getting Started guide is the first-use tutorial.

It should explain the minimum steps needed to:

• install and enable Model Weave
• open a sample model
• open the Obsidian command palette
• run the preview command
• check diagnostics
• try PNG export
• try Source Links when available

Command Guide

The Command Guide explains Obsidian commands provided by Model Weave.

It should group commands by purpose, such as:

• preview / index / export commands
• template insertion commands
• editing helper commands
• settings-related notes

Command names should match how users see them in Obsidian's command palette, using the Model Weave: prefix where appropriate.

FORMAT specifications

FORMAT documents define the structure of Model Weave Markdown model files.

They should explain:

• what each format is for
• required and optional frontmatter
• supported sections
• expected table headers
• safe writing rules
• common mistakes
• AI generation notes
• related samples

FORMAT documents should be strict about table headers and supported sections.

Samples

Samples provide concrete examples.

They should help users understand how FORMAT specifications are used in actual Markdown files.

Samples should not replace FORMAT specifications. FORMAT documents define the structure; samples show practical usage.

Dogfood models

Dogfood models are advanced examples and implementation maps.

They may include:

• source links
• implementation notes
• future design ideas
• internal structure of Model Weave itself
• AI-generated or AI-assisted model content

Dogfood models are useful as real-world examples, but they may contain experimental or future-oriented material. They should not be treated as the sole source of truth for implemented plugin behavior.

Standard FORMAT document structure

Each FORMAT document should generally use the following structure.

Not every section needs the same level of detail, but the order and intent should be consistent.

What this is for

Explain the purpose of the format.

This section should answer:

• What does this format represent?
• When should users use it?
• What should not be modeled with this format?

Minimal example

Provide the smallest useful example.

The minimal example should be short enough for a first-time user to copy and understand.

It should avoid advanced options unless required.

Full example

Provide a more practical example when useful.

The full example may include:

• multiple rows
• relationships
• notes
• Source Links
• render mode examples
• related model references

Do not make the full example too large. Larger examples should live in samples/.

Frontmatter

Document supported frontmatter fields.

Include:

• required fields
• optional fields
• expected values
• safe Wikilink usage
• examples

If a frontmatter field is not supported by the parser, do not document it as supported.

Sections

Document supported Markdown sections.

For each section, explain:

• what it represents
• whether it is required
• whether it is optional
• how it is parsed
• how it affects preview or diagnostics

Tables

Document expected table headers exactly.

This is especially important for AI-assisted generation.

For each table, include:

• section name
• expected header
• column meanings
• required / optional columns
• safe values
• notes on references or Wikilinks

Do not document unsupported columns.

Common mistakes

List mistakes that users or AI assistants often make.

Examples:

• adding unsupported columns
• using table headers from another format
• mixing model concepts
• using unsafe Markdown table syntax
• putting future design ideas in implemented sections
• using unquoted Wikilinks in frontmatter

AI generation notes

Explain how AI assistants should generate this format safely.

This section should include rules such as:

• preserve exact table headers
• do not add unsupported columns
• use simple scalar type names
• put extra information in notes
• use optional sections for additional context
• distinguish implemented behavior from future ideas
• use Source Links for traceability when useful

Related samples

Link to relevant files or directories under samples/.

Related samples should help users quickly find working examples.

AI-safe Markdown rules

When using AI to generate or update Model Weave Markdown, follow these rules.

Keep table headers exact

AI assistants must not add, remove, reorder, or rename table columns unless the FORMAT document explicitly allows it.

A table that looks natural to a human may still be invalid for the parser.

Do not add undefined columns

Do not add columns such as ref, rule, description, notes, source, or target unless the target FORMAT explicitly supports them in that section.

If extra information is useful, put it in:

• an existing notes column
• a supported optional section
• ## Notes
• ## Source Links
• a separate model file
• a TODO or guide file when appropriate

Quote Wikilinks in frontmatter

Frontmatter is YAML, not normal Markdown text.

When using Wikilinks in frontmatter, quote them.

Recommended:

source: "[[DATA-EXAMPLE]]"

Avoid:

source: [[DATA-EXAMPLE]]

If link behavior is not needed, a plain ID may be safer:

source: DATA-EXAMPLE

Avoid Wikilink aliases inside tables

Avoid table cell values like:

[[DATA-USER|User]]

Use a plain Wikilink instead:

[[DATA-USER]]

Wikilink aliases contain |, which can interfere with Markdown table parsing.

Avoid raw pipe characters inside table cells

Avoid values such as:

string | null
A | B | C

Prefer safer alternatives:

string
A / B / C

Use required, not_null, or notes to express optionality when the FORMAT supports it.

Prefer simple scalar type names

Prefer simple type names in table cells, such as:

• string
• number
• boolean
• date
• datetime

Avoid complex type expressions such as:

• string[]
• Array<string>
• Optional<string>
• string | null

If multiplicity or optionality matters, explain it in a supported column or in notes.

Separate implemented behavior from future ideas

Dogfood models and design notes may contain future ideas.

When generating or updating FORMAT documents, clearly distinguish:

• implemented behavior
• documented behavior
• experimental behavior
• future design ideas
• notes or TODOs

Do not describe future ideas as implemented behavior.

Use Source Links for traceability

Use ## Source Links when a model should point back to implementation files, tests, configuration, SQL, interface specs, or sample data.

Source Links help users verify AI-generated design models against the original source.

Stability labels

FORMAT documents should indicate whether a format is:

• stable / primary
• experimental / evolving
• internal / dogfood-only
• deprecated / legacy

Stable formats are recommended starting points for most users.

Experimental formats may be usable, but their documentation and modeling conventions may change.

Relationship to V0.8 rendering policy

V0.8 rendering policy describes the current renderer behavior.

This V0.8 documentation policy covers documentation structure and writing rules.

Use:

• V0.8 rendering policy for renderer behavior, render_mode, Custom / Mermaid policy, Mermaid Detail availability, and Mermaid Source / Debug behavior.
• This document for documentation structure, FORMAT specification structure, and AI-safe Markdown writing rules.

Maintenance rules

When updating FORMAT documentation:

1. Check the current implementation or parser behavior.
2. Check existing samples.
3. Preserve supported table headers exactly.
4. Do not document unsupported columns.
5. Add examples that are small enough to understand.
6. Link to larger samples instead of embedding large examples.
7. Add AI generation notes where the format is likely to be generated by AI.
8. Keep stable and experimental formats clearly separated.

Review checklist

Before accepting documentation changes, check:

• Does the document explain what the format is for?
• Is there a minimal example?
• Are frontmatter fields documented?
• Are supported sections documented?
• Are table headers exact?
• Are unsupported columns avoided?
• Are common mistakes documented?
• Are AI generation notes included?
• Are related samples linked?
• Are implemented behavior and future ideas clearly separated?
• Are links valid?

Summary

V0.8 documentation policy makes Model Weave FORMAT documentation predictable and safer to use.

The goal is not only to document the current formats, but also to make them easier for AI assistants to generate correctly and easier for humans to review.