Writing documentation for your house

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?
• What model of filter do I need to buy for my HVAC?

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 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.

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 hand-written 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 my phone.

So, for implementing the documentation site itself, I’m a big fan of Astro Starlight. I created a git repo for my house, which I use to store this documentation (automatically built and deployed via Cloudflare Pages). 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
│   ├── closing-forms.pdf
│   └── ...
├── diagrams
│   ├── floorplans.drawio
│   ├── upstairs-office.drawio
│   └── yard-wireframe.drawio
├── docs
│   ├── astro.config.mjs
│   ├── dist
│   ├── Justfile
│   ├── mise.toml
│   ├── node_modules
│   ├── package.json
│   ├── pnpm-lock.yaml
│   ├── pnpm-workspace.yaml
│   ├── public
│   ├── src
│   │   ├── assets
│   │   ├── components
│   │   ├── content
│   │   │   └── docs
│   │   │       ├── changelog.mdx
│   │   │       ├── guides
│   │   │       ├── index.mdx
│   │   │       ├── introduction.mdx
│   │   │       └── reference
│   │   ├── content.config.ts
│   │   ├── fonts
│   │   └── styles
│   └── tsconfig.json
├── financing
│   └── financing.pdf
├── guest
│   ├── guest-guide.pdf
│   ├── guest-guide.typ
│   ├── wifi.pdf
│   └── wifi.typ
├── inspections
│   ├── 2020-inspection-report.pdf
│   └── ...
├── insurance
│   └── policy.pdf
├── README.md
├── taxes
│   ├── 2023_property-tax.pdf
│   ├── 2024_property-tax.pdf
│   └── 2025_property-tax.pdf
└── utilities
    └── internet-lease.pdf

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-based 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. Having a changelog makes it very easy to look up when we did particular work and how much it cost.

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!