Skip to main content

SFDS Document Templates

These are the reusable starter documents every new standard suite copies into its own directory and fills in. Replace every bracketed placeholder before treating a filled copy as authoritative.

Standard-Specification.md​

The starter shape for a new standard's primary specification.

# [Standard Name]

## Status

[Maturity] v[Version].

## Scope

Describe what this standard governs.

## Does Not Govern

Describe what this standard intentionally leaves to other standards or projects.

## City Hall Role

Describe how this standard fits the City Hall system and which adjacent standards it depends on or complements.

## Required Behaviors or Artifacts

- `README.md` as the role statement and document map.
- This primary specification as the authoritative ruleset.
- `[StandardName].manifest.toml` for the standard suite.
- Domain schemas or adopter manifest templates, when applicable.
- Templates.
- Examples.
- Adoption guide.
- Validation checklist.
- Changelog.

## Manifest Model

Describe the difference between the standard-suite manifest and any adopter-facing manifests or schemas.

## Adoption

Describe who adopts this standard and which files they copy, create, fill in, or validate.

## Validation

Describe how suite conformance is checked.
Describe how adopter or domain conformance is checked, if different.

## Compatibility Policy

Describe which changes are allowed in minor versions and which require a major version.

## Adoption Blockers

List conditions that block stable adoption of this standard or release of governed artifacts.

Adoption-Guide.md​

# [Standard Name] Adoption Guide

## When To Adopt

Describe when a project should use this standard.

## Required Steps

1. Read the specification.
2. Read `README.md` to understand the standard's City Hall role and related standards.
3. Read `[StandardName].manifest.toml` to understand the suite boundary.
4. Copy required adopter templates.
5. Fill in any adopter manifest or governed artifact records.
6. Run or complete validation.
7. Record known gaps.

## Manifest Model

`[StandardName].manifest.toml` describes this standard.
Adopter manifests, schemas, and document templates describe the projects or artifacts governed by this standard.

## Adoption Complete

Adoption is complete when the adopter has the required records, has completed validation, and has documented any known gaps or deferred artifacts.

Validation-Checklist.md​

# [Standard Name] Validation Checklist

## Suite Validation

- [ ] `README.md` exists and explains the standard's City Hall role.
- [ ] Primary specification exists and is named by the README.
- [ ] `[StandardName].manifest.toml` exists and describes the standard suite.
- [ ] Required suite docs exist.
- [ ] Scope is clear.
- [ ] Non-goals are clear.
- [ ] Adopter schemas or manifest templates are separate from the standard-suite manifest.
- [ ] Templates exist or are explicitly deferred.
- [ ] Examples exist or are explicitly deferred.
- [ ] Validation procedure is documented.
- [ ] Known gaps are recorded.

## Adopter or Domain Validation

- [ ] Adopter-required files are named.
- [ ] Adopter validation steps are documented or explicitly deferred.
- [ ] Required templates and schemas are present when the standard governs project or artifact records.

CHANGELOG.md​

# [Standard Name] Changelog

## 0.1.0 - YYYY-MM-DD

- Initial draft.