Writing Documentation for Your House

2023-11-26 - (6 min read)

Have you considered writing technical documentation for your house? As a first time homeowner, there have been numerous times where I wish I had some documentation to reference for a whole slew of scenarios. As an engineer, I write documentation all the time to answer these questions and build up a knowledge base other team members can refer to. I think this should apply to housing.

Motivation

As a first time homeowner, I have had so many questions about our house. Some real examples:

  • When was this carpet installed?
  • How do I turn off the water mains?
  • How is the irrigation system set up in this house?
  • Where are all the sprinkler heads?
  • What’s the model of my dishwasher again? I need the user manual.
  • Why is the water pressure so high?
  • What company is in charge of my sewage?
  • What electrical circuits are in the house?
  • Are there networking cable runs?
  • What color exactly is this paint?

Unfortunately, for most of these questions, I either had no answer, or I needed to go investigate and/or reverse-engineer directly.

As I gathered up these questions, I realized that when it comes to my house, what I actually wanted was a user manual of sorts. I wanted good technical documentation, much like good software provides. So, as we’ve lived here, I’ve started to create just that.

Recommended Framework

When looking at some of my questions, I found that my favorite technical documentation framework, Diátaxis, would work great here.

For those of you unfamiliar, this framework suggests organizing documentation into four modes: tutorials, how-to guides, technical reference, and explanations.

The 4 modes of documentation

I’ll refer you to the site itself to learn about its benefits and see examples.

The Changelog

In addition to these four categories, I also add an important page: a changelog.

While I can’t answer the questions in the past, I can at least have a record of important changes during my ownership. On this page, I log all major changes to the house, such as plumbing repairs (and their costs), irrigation system upgrades/changes, carpet installation, remodeling, etc.

With it, I can easily answer questions like "When did this carpet get redone, what square footage was needed, and how much did it cost?"

Implementation

Let me preface this section by saying that my implementation is almost certainly too complex. Yours might be a binder with notes. Or, maybe a Google Doc. Or, maybe it’s a YouTube channel with a bunch of short videos. I personally like having a website I can pull up and search on any device.

So, for implementing the documentation site itself, I’m a big fan of Material for Mkdocs. I created a git repo for my house, which I use to store this documentation (automatically built and deployed via Netlify). In addition, this git repo serves as a convenient place to store other important, house-related documents.

Directory Structure

Here is an example directory structure (not real, but illustrative).

├── contracts
│  ├── repc.pdf
│  ├── closing-forms.pdf
│  ├── water-shares.pdf
│  └── title.pdf
├── diagrams
│  └── yard-wireframe.drawio
├── docs
│  ├── docs
│  │  ├── assets
│  │  ├── changelog
│  │  ├── explanations
│  │  ├── how-to-guides
│  │  ├── index.md
│  │  ├── reference
│  │  ├── robots.txt
│  │  └── tutorials
│  ├── mkdocs.yml
│  └── requirements.txt
├── financing
│  └── financing.pdf
├── inspections
│  ├── 2020-inspection-report.pdf
│  ├── 2022-inspection-report.pdf
│  └── replacement-value-estimate.pdf
├── insurance
│  └── Binder.pdf
├── Justfile
├── netlify.toml
├── README.md
├── taxes
│  ├── 2023_property-taxes.pdf
│  └── 2023_property-valuation.pdf
└── utilities
   ├── water-application.pdf
   └── fiber-internet-lease-agreement.pdf  

Mkdocs Configuration

For my personal documentation, I suggest an mkdocs.yml configuration like the following:

# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
site_name: Housing Documentation
theme:
  name: material
  font:
    text: Atkinson Hyperlegible
    code: Source Code Pro
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.sections
    - navigation.indexes
    - content.code.copy
    - content.code.annotate
    - content.action.edit
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
repo_url: https://github.com/lukehsiao/example
repo_name: lukehsiao/example
edit_uri: edit/main/docs/docs/
plugins:
  - glightbox
  - search
  - git-revision-date-localized:
      enable_creation_date: true
markdown_extensions:
  - admonition
  - toc:
      permalink: true
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - attr_list
  - md_in_html
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.smartsymbols
  - pymdownx.betterem
  - footnotes

I’d suggest using a codename for the site of course. The public Internet doesn’t need to know any personally locating information. Similarly, I just have a robots.txt set to disallow all crawlers.

This configuration also assumes you have:

  • mkdocs-git-revision-date-localized-plugin
  • mkdocs-glightbox
  • mkdocs-material

in your requirements.txt.

Local Previews with Just

You’ll also notice a Justfile in my example tree. I’m a big fan of just as a command runner. I have a target like the following to serve the docs locally for previewing:

# Serve docs locally
serve:
    #!/usr/bin/env bash
    set -euxo pipefail
    VENV_PATH="{{justfile_directory()}}/.venv-docs/"

    cd {{justfile_directory()}}/docs;
    if [ ! -d $VENV_PATH ]; then
        echo "${VENV_PATH} not found, creating one...";
        python -m venv $VENV_PATH;
        source ${VENV_PATH}bin/activate;
        pip install --upgrade pip;
        pip install -r requirements.txt;
        mkdocs serve
    else
        echo "${VENV_PATH} already found.";
        source ${VENV_PATH}bin/activate;
        mkdocs serve
    fi;

Conclusion

This has been a nice quality-of-life improvement for my family when it comes to having a simple place to find information. I have an irrigation-system reference page I used frequently when trying to understand how our system worked. I love the user-manual reference page, which collects links to PDFs or web user manuals of all of the appliances, consumer electronics, etc. we use; if I need to perform a routine cleaning of the dishwasher, I’m about 3 clicks from the user manual without needing to search or find model numbers. Having a nice how-to guide for turning off the water mains adds a sense of security in an emergency.

I feel like this adds value to our home, and look forward to being able to pass on this documentation to the next owners, so they will have all the answers to the questions I had. Of course, it is highly unlikely the next owners will want such an involved tech stack. But even in that case, I can just share the plain-text markdown files used to generate the site: it will still be far better than nothing.

Comments on HN

There are many other great ideas and discussion on HackerNews!

Posts from blogs I follow

Benchmarking Bowtie2 Threading

I've been using Bowtie2 to align reads to genomes, and one of it's many settings is the number of threads. While sometimes people advise using about as many threads as your machine has cores, but if I'm running on a big machine are there diminishing retur…

via Jeff Kaufman's Writing December 01, 2023

Control - how to make a game enjoyable for casual audiences

I’ve decided to intentionally take more time to play video games this year, since it’s a relatively healthy way to escape from the real world once in a while. A friend recommended one game in particular: Control: Ultimate Edition. During the Steam summer s…

via ./techtipsy December 01, 2023

clang now makes binaries an original Pi B+ can't run

I have a bunch of Raspberry Pi systems all over the place, goofy things that they are. They do dumb and annoying jobs in strange locations. I even have one of the older models, which is called just the B+. You can think of it as the "1B+" but apparen…

via Writing - rachelbythebay December 01, 2023

Generated by openring-rs


Last Updated: 2023-12-01