Handbook for the House

Now that I have a century-old house to manage, I’ve found myself struggling to keep on top of all the things that need doing. Not only that, but knowing which need to be done by when, which require tools or parts, and which are on hold can be tricky. To alleviate these problems, I’ve come up with a plan…

Inventory what needs knowing

There are tons of things in the house that need inventorying and they count far above the maximum number of thoughts a brain can hold. Don Norman talks about “knowledge in the mind” and “knowledge in the world” as a way to imagine how a set of records should be. I’ve found that putting knowledge into a repository that can evolve, deliberately, over time is the best. But throwing images, schematics, text files, PDFs, and other stuff into a directory and hoping the naming scheme is enough just doesn’t cut it.

The starting point

Some time ago, I made a “suddenly remote handbook” template. It has a space for a lot of structured information (by organizational structure) and a place for collaborating on that information (GitLab Issues).

It also renders into a static site which is a nice way to have point-in-time access from anywhere in the world if something comes up. The static site has flexsearch and a nice heirarchy, per-page table-of-contents, and dark mode so that should suffice.

How to organize all this?

I’ve applied the PARA method (Projects, Areas, Resources, and Archives) to the house. It uses GitLab issues for projects and then directories in the repo for Areas, Resources, and Archives.

• Projects are things that will happen
  • Tasks around the house will be projects
  • They live in GitLab issues

In the repository, the slower-moving information is stored. It’s changed via merge requests such that a change that needs validation can be suggested and talked about before it’s applied.

• Areas are categories of things that can happen
  • Types of things to work on (like eletrical, plumbing, structural, cosmetic, landscaping)
  • They live in the repository under Areas
• Resources are the slow moving reference materials
  • A heirarchy of broad location and then specific location
  • Examples
    • 1st Floor / Kitchen
    • 2nd Floor / North Bedroom
    • Exterior / Front Porch
    • Garage / Roof
• Archive is where records of issues get boiled down into highlights and stored for later

So let’s look at an a-ha moment

I’m walking around my yard and see a missing storm window.

I can snap a picture of the window that’s missing the storm window pane and email it to my service desk address or open my browser, create an issue, and upload the image. Thanks to service desk, I don’t even have to be logged in!

Things to include in the issue, either at inception or when reviewing:

1. Short description of the thing
2. Needed parts (as checklist items)
3. Needed tools (as checklist items)
4. Research topics (as checklist items)
5. Steps to take (as checklist items)
6. Or vendors to engage if it’s outsourced

Assign a milestone to set which quarter I expect to get to the issue. Typically if it’s something indoors, I’ll choose winter. If weather is a consideration, I may choose Spring or Summer. It doesn’t seem helpful to go any more granular than this.

Current milestone options:

• 2023-Winter
• 2023-Spring
• 2023-Summer
• Hold

Assign labels!

Notice that I’ve checked all the labels but there are some obvious pairs.

• diy vs contractor
• need parts, need tools vs ready
• records means just about recording existing information in the repo
• meta is for issues related to the GitLab project or SSG

Really!? Lables?! why

As annoying and bureaucratic is labels are, they really help under 1 very important situation:

I’m standing in the Ace Hardware with a blank expression on my face. There is something I need to get for a project that I’m going to do over the weekend. What in tarnation…

In these scenarios, I can quickly pull up my board and see what projects require tools and suppiles!

The other time these labels are integral is when the ready label is on, I don’t have to bother trying to come up with something to do during project time. Just go to the top of the list and start cranking!

Backlog grooming for the house

As dumb as it sounds, it really helps re-prioritize and focus on the most important stuff. The wife and I sit down and talk through the lists. At the end everything is different and more aligned with our current needs.

Like all interpersonal activities, restating what someone else asks for reduces scope of things by 70%. Certain words can be loaded with facets when interpreted literally that disappear when restating it clarifies the person was speaking generally.

Put xmas lights around the house

Okay, I’ll get the 32-foot extension ladder

Why? the bushes are only 11 feet tall

Oh, just the bushes! I can do that in an hour

So then work the issue!

Get the parts, move it across the board. Get the tools, throw it in ready. Get it done, create a merge request.

1. Modify the areas affected
2. Modify the resources affected
3. Copy and clarify the issue contents into an archive record if required

Once that MR is done and merged, it’ll close the issue.

Let’s get into these modifications. What’s an Area page look like?

Each branch (The Areas page, Electrical, hvac, etc) have the option to contain their own information. These typically have some themes or trends or intro knowledge that can help make sense of the children. Children can be more branches or leaves.

Branches get an _index.md markdown file which has a bit of forematter for menu formatting. If any content is after the forematter, the page is clickable in the menu. Without any content in the page, it’ll just be a menu item.

I made everything from the 2nd tier in the herarchy collapse by using forematter’s bookCollapseSection: true.

---
title: Plumbing
weight: 20
bookCollapseSection: true
---

This makes it easier to drill into the thing you need to find.

Leaves can be a file or a folder

I typically use a folder for each leaf so I can leave images and PDFs in the same directory as the content. Hugo has some interesting behaviors about referencing stuff elsewhere in the heirarchy so keeping it all in a bundle together is the easiest to manage. If areas are separated or coalesced in the future, fewer links will need to be addressed.

Explaining it is tough

I’d love to open source the whole house repo but it’s just a lot of sensitive information all in one place.

Area page for solar has sections for vendor selection, nice irradiance images, an equipment plan, and links to all the technologies and things I want to add later.

The Area page for the water heater has some information about the old water heater and why 40 gallons wasn’t enough and some information on the new water heater, how it’s wired to the breaker, how it’s connected to the vairous drains and blow-off things, and why it is where it is vs where the old one was.

There’s a link in that area page to the archive for 2022-09 Water Heater Upgrade where I lay out my original plan, how things went awry for 3 days, how it all eventually came together, and a whole bunch of stuff about rebates and things that I’m going to need at tax time.

These pages are full of images that were taken at the time. Any time a wall is opened up or a hole is exposed, I point my camera in and take a few pictures for reference later. It comes in handy far more often than it should.

What are Resources for if Areas have all the info about all the stuff?

Resources fill in the physical relationships between things by tying them to a room.

The first part of the reference is about what the room is used for and an inventory of outlets, switches, lights, radiator, plumbing, and access holes.

The second part is a set of links to other pages about areas that impact the room.

Example me!

There are stoves in a few of the rooms and each one has a different mode of operation. They all have a similar premise, make heat. The way they do this is complicated by “use an augur” or “here’s a lever that can dump CO2 into your house”.

So each room with a stove has a summary of how it works and a link to the PDF owner’s manual for cleaning and repair instructions.

There’s also a growing inventory of “stuff” in each room. Furniture and electronics and other things that insurance folks would be interested in if there was a catastrophe. These things are included where the items are important but as time goes on, I’ll probably lower the threshold to include more lower-value items.

Let GitLab build and publish for you

The pipeline is pretty boring. It just runs hugo and tars up the public folder.

Now what?

Having the contents of the repo in a browser that is easy to navigate and reference is so nice.

The site also has the helpful links at the bottom to hit the WebIDE and make adjustments, start stub MRs, or create issues.

Some other stuff that’s delightful about this setup

There are a lot of enjoyable parts to getting stuff done.

Checkboxes all over

The experience of checking off items is just so nice. I add tools and parts I already have and then check them off when adding a new thing to do. Gimme that reward trigger.

Git Tags

When something big happens or enough time elapses, it’s nice to tag a commit. It makes searching through older repo stuff easier since git makes sure it’s stored forever but less accessible.

FlexSearch is so good

I honestly haven’t looked into it and it makes no sense since the site is static but I can somehow search the whole site instantly from the little search box in the corner and I love it.

It does have to be on its own domain for this to work. Or you can hard-code the path into your deployment.

GitLab Pages with Authorization controls

I can use the public GitLab.com instance to host this stuff and then simply enable the pages authorization so only project members can access the page.

It’s just one less service to run myself.

Milestone view

Going back and looking at closed milestones is another satisfying activity. Shows the huge amount of stuff that got done. Shows the moderate amount of stuff that didn’t get done.

Git Book Shortcodes

It can do warning/error style text using {{hint}}, Columns, expand blocks, tabs, and mermaid diagrams.

It’s the same theme I used for the Remote Handbook but it’s still fantastic.

DARK MODE for the win.

The theme lives here: https://github.com/alex-shpak/hugo-book

Next Steps?

I always end a story with steps you can take if you want to embark on whatever adventure I’m describing.

This is no different that the remote handbook’s getting started readme. Instead of departments and other nonsense, make your own PARA or similar heirarchy. If you’re going to be teamworking it, use merge requests more for planning and dicussion. If you’re single player mostly, you can use commit messages like closes #23 and just commit to main and keep it simple.

Hit me up if you have comments or questions!