| name | documentation |
| description | Documentation standards, writing style, markdown conventions, and sources of truth for ADAMANT iOS. Use when writing or updating documentation. |
| license | Apache-2.0 |
| compatibility | Markdown, documentation tools |
| metadata | {"project":"adamant-ios","domain":"documentation"} |
Documentation Standards
Documentation conventions, writing style, and sources of truth for ADAMANT iOS.
Writing Style
- In bullet and numbered lists, do not add a trailing period when an item contains one sentence
- If an item contains two or more sentences, end every sentence with a period
Examples:
<!-- Good: single sentence, no period -->
- This is a single sentence item
<!-- Good: multiple sentences, all have periods -->
- This is the first sentence. This is the second sentence.
<!-- Bad: single sentence with period -->
- This is a single sentence item.
Markdown Lint Rules
- For every Markdown list, keep one blank line before the list and one blank line after the list
- Always keep a blank line between a heading and the list that follows it to satisfy MD032 (
blanks-around-lists)
- Use fenced code blocks with matching opening and closing fences
- Include a language tag when applicable (
swift, bash, etc.)
- Follow other best practice markdown rules
Example:
## Section Title
This is introductory text.
- List item 1
- List item 2
- List item 3
This is text after the list.
Sources of Truth
Use these sources when implementing or reviewing changes:
Documentation Drift Policy
When behavior and docs diverge:
- Document exact mismatch with file/path references
- Propose synchronized updates in this repo and companion ADAMANT docs/spec repos when required
- If cross-repo changes cannot be included immediately, open linked follow-up issues
Priority Rules
If sources disagree:
- Treat current repository behavior and passing tests as implementation truth
- Do not silently ignore mismatches; document them and propose synchronized fixes
When to Use This Skill
Activate this skill when:
- Writing new documentation
- Updating existing docs
- Formatting markdown files
- Resolving documentation conflicts
- Understanding documentation sources
- Creating or updating README files
See Also
