62 lines
2.4 KiB
Markdown
62 lines
2.4 KiB
Markdown
---
|
|
title: Documentation Philosophy
|
|
description: Principles for writing durable, public-facing technical documentation in Den Vault
|
|
tags:
|
|
- about
|
|
- documentation
|
|
- writing
|
|
category: about
|
|
created: 2026-03-14
|
|
updated: 2026-03-14
|
|
---
|
|
|
|
# Documentation Philosophy
|
|
|
|
## Summary
|
|
|
|
Documentation in Den Vault is written to be durable, public, and technically useful. Each document should explain a concept clearly enough for another engineer to apply it without needing access to private context.
|
|
|
|
## Why it matters
|
|
|
|
Unstructured notes decay quickly. Public technical documentation only becomes valuable when it is scoped well, written clearly, and maintained as part of the normal engineering workflow.
|
|
|
|
## Core concepts
|
|
|
|
- Write reusable technical documentation, not private memory aids
|
|
- Prefer explanation plus implementation guidance over checklist-only pages
|
|
- Keep documents scoped so they can be updated without rewriting the entire vault
|
|
- Use frontmatter and predictable structure for discoverability
|
|
- Keep writing human-scale, legible, and maintainable rather than optimized for feed-style consumption
|
|
|
|
## Practical usage
|
|
|
|
In practice, this means:
|
|
|
|
- Explaining why a technology or pattern matters before diving into commands
|
|
- Using placeholders instead of sensitive values
|
|
- Linking to upstream docs for authoritative behavior
|
|
- Revising pages when tooling or best practices change
|
|
- Preserving enough warmth and clarity that the docs feel written for people, not dashboards
|
|
|
|
## Best practices
|
|
|
|
- Prefer official documentation and standards as primary sources
|
|
- State assumptions clearly when a topic has multiple valid designs
|
|
- Keep examples small enough to understand but complete enough to use
|
|
- Separate conceptual articles, operational guides, and tool references
|
|
- Avoid unnecessary jargon when simpler language communicates the same idea accurately
|
|
|
|
## Pitfalls
|
|
|
|
- Mixing personal environment details into public docs
|
|
- Copying large blocks from upstream sources instead of summarizing them
|
|
- Writing instructions that depend on outdated versions or defaults
|
|
- Creating giant pages that cover many unrelated concerns
|
|
- Writing in a polished but impersonal style that obscures the actual operational intent
|
|
|
|
## References
|
|
|
|
- [Diataxis](https://diataxis.fr/)
|
|
- [Write the Docs: Docs as Code](https://www.writethedocs.org/guide/docs-as-code/)
|
|
- [Google Developer Documentation Style Guide](https://developers.google.com/style)
|