Skip to content

Documentation Rules & Scope

Purpose of This Documentation

This knowledge base exists to document how our home and property work, in a way that is:

  • Understandable by someone who did not build it
  • Usable during stressful situations (power loss, outages, failures)
  • Durable over time, even as systems change

A primary goal is that my wife can use this documentation independently to:

  • Understand how systems are intended to work
  • Restore service when something breaks
  • Decide when professional help is required

This documentation is not meant to prove technical cleverness. Clarity and survivability take priority over completeness.

Intended Audience

Primary audience:

  • My wife

Secondary audiences:

  • Family members
  • Contractors or technicians
  • A future version of myself who has forgotten details

If a section cannot be understood by the primary audience, it should be revised.

Scope: What Belongs Here

This documentation should include:

  • How major systems work at a high level
  • Physical locations of equipment
  • Normal operation vs failure modes
  • Safe recovery procedures
  • Where to find credentials or backups (but not the secrets themselves)

This documentation should not include:

  • Passwords or secret keys
  • Deep implementation details unless they aid recovery
  • Experimental notes that are not in active use

Writing Style Guidelines

  • Prefer plain English over technical terms
  • Define acronyms the first time they appear
  • Use lists and headings generously
  • Include diagrams or maps when location matters
  • Assume the reader is intelligent but unfamiliar

When in doubt, write for calm understanding rather than speed.

Structure Conventions

  • Each major system folder follows a standard template:
  • 00 - Overview.md
  • 01 - Physical Layout & Locations.md
  • 02 - Components.md
  • 03 - Normal Operation.md
  • 04 - Failure & Recovery.md
  • _assets/ (maps, diagrams, photos, PDFs)
  • Physical systems are documented before logical systems.
  • Sensors and automation are documented under the system they serve.

File and Folder Naming

  • Major sections are stored under docs/ and are named with a numeric prefix so they sort in a predictable order (e.g., 07 - Sprinkler and Drip Irrigation Systems).
  • The site entry point is docs/index.md.
  • Within each major system folder, the file prefix numbers (00, 01, 02, etc.) indicate reading order.
  • The _assets/ folder contains non-Markdown artifacts referenced by pages (maps, images, exported diagrams, PDFs). Keep filenames descriptive.
  • Use Obsidian wiki-links for internal references, e.g. [[01 - Documentation Rules & Scope]].
  • Prefer linking to the most stable page (usually the 00 - Overview page for a system).
  • Avoid duplicate pages for the same concept.

How to Use This Documentation

If something is broken:

  1. Start with the relevant system’s Overview
  2. Identify whether the issue is power, network, or mechanical
  3. Follow recovery steps in order
  4. Stop if a step feels unsafe or unclear

If something needs improvement:

  • Update the documentation as changes are made
  • Note open questions in the Open Questions & TBD section

Standard Workflow for Adding a New System

When adding documentation for a new major system, follow this workflow:

  1. Create the system folder

  2. Create a new folder under docs/ using the numeric prefix convention, e.g. 06 - Electrical & Power.

  3. Apply the standard template

  4. Run the apply_system_template.sh script from the repository root.

  5. This will create the standard set of files and the _assets/ folder without overwriting existing content.

  6. Draft the overview first

  7. Start with 00 - Overview.md.
  8. Write in plain English, focusing on what the system is, what it does, and why it matters.

  9. Do not worry about filling in all other sections immediately.

  10. Add to site navigation when ready

  11. Add the system’s 00 - Overview.md page to the MkDocs nav section only after the overview is stable enough to be useful.
  12. Defer adding detailed sub-pages to navigation until they provide real value to readers.

This workflow is intentionally incremental. Documentation should grow as understanding grows, not all at once.

Review & Maintenance

This documentation should be reviewed:

  • After major changes
  • At least once per year
  • Whenever a procedure is confusing or incomplete

Feedback from non-technical readers is especially valuable.