first version of the knowledge base :)

00 - About/documentation-philosophy.md

@@ -0,0 +1,61 @@
+---
+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)