Content lifecycle
MarkStack stores/builds documentation. It does not assign review owners, enforce approval queues, send reminders, commit browser edits to Git or create per-page history. Keep those practices in a real source/review process and document their boundaries.
Lifecycle matrix
| Stage | Completion evidence |
|---|---|
| Define | Reader need and success condition |
| Draft | Complete source, not heading placeholders |
| Review | Facts, risk, audience and source diff checked |
| Build | Isolated artifact, no generation errors |
| Reader test | Routes/search/media/tasks actually usable |
| Release | Reviewed artifact on intended host |
| Maintain | Real owner/date/version context |
| Retire | Old link/asset behavior verified |
A source save is not approval, publication or deployment. Shared administrator publisher includes saved source from every writer, not only selected page. A team needs a publishing agreement outside application: who reviews, who releases, what saved material is in scope and how rollback is handled.
Define one reader task
For fictional Field Guide: “A new teammate can verify installed tools before building.” Success means required Node version is clear, commands are read-only and run in stated shell, expected results are recognizable and missing-tool recovery is described.
| Procedure section | Purpose |
|---|---|
| Purpose/audience | Who needs this and why |
| Prerequisites | Required versions, permissions, context |
| Steps | Complete sequence and exact target |
| Expected result | How to recognize success |
| Failure | How to diagnose without repeating blindly |
| Recovery | Safe return/restore path and limits |
| Sources/related tasks | Maintenance context and next task |
A reference instead needs exact fields, defaults, bounds, precedence and errors. An example should teach one distinct scenario, not repeat boilerplate across many pages to appear longer. Keep command authority separate from documented command behavior.
Write and review source
Choose one maintainer in external workflow and keep source path, operating-system/version assumptions and evidence together. Unsupported ownership/status frontmatter is data only. Use visible notes or Git/review tools when decisions must be recoverable.
Review commands for working directory, shell, placeholders, effects and undo costs. Check exact path before deletion/output replacement. Review screenshots/download bytes for identities/keys/hidden metadata. Illustrative host/service snippets must say what was tested and what remains environment-specific.
For file/Git writing, inspect diff and build disposable output. For browser writing, confirm actual server source and preserve unsaved work before review. Save/Publish does not automatically produce a Git commit/PR. Ordinary Markdown Save has no stale revision merge; coordinate writers on shared pages.
Review evidence honestly
| Claim | Required evidence |
|---|---|
| Syntax-valid example | Parser/tool accepted exact input |
| Working local example | Actual local result inspected |
| Production service works | Target service/permissions/network exercised |
| Reader accessible | Intended user and denied-user host checks |
| Download correct | Open actual returned bytes |
| Complete feature coverage | Source branches/tests mapped, not word count |
A systemd syntax check is not proof daemon starts under correct owner/sandbox/TLS. Local browser emulation is not physical Safari testing. A green build is not correct links/content/privacy. Keep those qualifiers next to example/result instead of turning prep into production claims.
Publish and release
- Reconcile all saved work included in shared input.
- Freeze reviewed source/artifact under chosen team process.
- Build isolated output and run link/anchor/search/resource checks.
- Inspect both themes and phone/desktop, diagrams and copied commands.
- Retain prior source/runtime/artifact and documented rollback route.
- Release through intended host method within authority.
- Verify actual root/deep/old routes and cache/resources.
- Record result, limitations and next owner action.
There is no built-in page-level approval gate or selective “only my saved page” publication. An external CI trigger must be documented as that pipeline’s behavior, not MarkStack’s automatic service. Review and release owns artifact/host checks.
Ownership and dates
Use updated only after actual factual/usability review. Do not bump every date on every build to make stale instructions look current. Record changed assumptions and the tested versions rather than implying indefinite freshness.
MarkStack does not enforce owner, expiry, review_due or approved metadata. If your organization needs enforcement, use an external workflow and describe it precisely. A search result/date is not approval or a production security certificate.
Import in a staging tree
| Import item | Review |
|---|---|
| Frontmatter | YAML-only types/delimiters |
| Titles | ASCII slug and collisions |
.md links |
Rewrite to real reader routes |
| Fragments | Generated heading IDs |
| Media | Selected static bytes, audience and prefix |
| Remote assets | Network/privacy/offline behavior |
| Unsupported dialect | Rewrite or explicit limitation |
| Ownership | Real maintainer/review record |
Keep original recoverable and build new material separately before replacing live reader. Importing all files successfully is not completion if readers cannot follow tasks, diagrams fail or links go to old source platforms.
Non-Latin title/heading limits need actual generated-route review at this pin. Preview parser/plugin differences are not universal import validation. Do not enable executable frontmatter or raw HTML to bypass compatibility work.
Retire without dead ends
| Choice | Work required |
|---|---|
| Deprecation page | Useful replacement and reason |
| Host redirect | Supported rule, actual status/destination check |
| Remove source | Build output and obsolete host file removal |
| Remove asset | Direct old asset URL/cache check |
| Hide sidebar | Presentation only, not retirement/privacy |
Inventory inbound links, readers and assets first. A deprecation note should identify a usable replacement, not promise a future unwritten chapter. MarkStack creates no automatic redirect map.
Add-only host uploads can leave removed pages/assets accessible. Verify old URL and direct bytes after release. Confidential accidental publication needs incident/host response under an approved plan; hidden flag or deleting one Markdown link is not a remedy.
Keep one dependable record
Prefer one full installation/recovery procedure with links from related chapters, not many divergent copied command lists. Keep source history and protected runtime/artifact backups. Generated HTML and browser drafts do not reconstruct all accounts/settings/history/source intent.
After release, record changed reader tasks, actual checks and remaining untested conditions. Maintenance is complete when another person can understand intended source, published state and recovery without guessing. Validation limits and Backup and restore state measured versus operator responsibilities.