Home Documentation

Documentation Rules & Scope

4 min read

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 index
  • 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

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

  2. Apply the standard template

    • Run the apply_system_template.sh script from the repository root.
    • This will create the standard set of files and the _assets/ folder without overwriting existing content.

  3. Draft the overview first

    • Start with 00 - Overview.md.
    • Write in plain English, focusing on what the system is, what it does, and why it matters.
    • Do not worry about filling in all other sections immediately.

  4. Add to site navigation when ready

    • Add the system’s 00 - Overview.md page to the MkDocs nav section only after the overview is stable enough to be useful.
    • 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.

Graph View