Writing Documentation for Your Home
Have you ever thought-about writing technical documentation for your home?
As a primary time house owner, there have been quite a few instances the place I want I had some documentation to reference for an entire slew of eventualities.
As an engineer, I write documentation on a regular basis to reply these questions and construct up a information base different staff members can check with.
I feel this could apply to housing.
As a primary time house owner, I’ve had so many questions on our home.
Some actual examples:
- When was this carpet put in?
- How do I flip off the water mains?
- How is the irrigation system arrange on this home?
- The place are all of the sprinkler heads?
- What’s the mannequin of my dishwasher once more? I would like the person guide.
- Why is the water stress so excessive?
- What firm is answerable for my sewage?
- What electrical circuits are in the home?
- Are there networking cable runs?
- What colour precisely is that this paint?
Sadly, for many of those questions, I both had no reply, or I wanted to go examine and/or reverse-engineer straight.
As I gathered up these questions, I noticed that on the subject of my home, what I really needed was a person guide of kinds.
I needed good technical documentation, very similar to good software program gives.
So, as we’ve lived right here, I’ve began to create simply that.
When taking a look at a few of my questions, I discovered that my favourite technical documentation framework, Diátaxis, would work nice right here.
For these of you unfamiliar, this framework suggests organizing documentation into 4 modes: tutorials, how-to guides, technical reference, and explanations.
The 4 modes of documentation
I’ll refer you to the location itself to find out about its advantages and see examples.
The Changelog
Along with these 4 classes, I additionally add an vital web page: a changelog.
Whereas I can’t reply the questions up to now, I can at the very least have a report of vital modifications throughout my possession.
On this web page, I log all main modifications to the home, resembling plumbing repairs (and their prices), irrigation system upgrades/modifications, carpet set up, transforming, and many others.
With it, I can simply reply questions like “When did this carpet get redone, what sq. footage was wanted, and the way a lot did it price?”
Let me preface this part by saying that my implementation is nearly definitely too advanced.
Yours is likely to be a binder with notes.
Or, perhaps a Google Doc.
Or, perhaps it’s a YouTube channel with a bunch of brief movies.
I personally like having a web site I can pull up and search on any system.
So, for implementing the documentation web site itself, I’m an enormous fan of Material for Mkdocs.
I created a git repo for my home, which I take advantage of to retailer this documentation (routinely constructed and deployed through Netlify).
As well as, this git repo serves as a handy place to retailer different vital, house-related paperwork.
Listing Construction
Right here is an instance listing construction (not actual, however illustrative).
├── contracts
│ ├── repc.pdf
│ ├── closing-forms.pdf
│ ├── water-shares.pdf
│ └── title.pdf
├── diagrams
│ └── yard-wireframe.drawio
├── docs
│ ├── docs
│ │ ├── property
│ │ ├── changelog
│ │ ├── explanations
│ │ ├── how-to-guides
│ │ ├── index.md
│ │ ├── reference
│ │ ├── robots.txt
│ │ └── tutorials
│ ├── mkdocs.yml
│ └── necessities.txt
├── financing
│ └── financing.pdf
├── inspections
│ ├── 2020-inspection-report.pdf
│ ├── 2022-inspection-report.pdf
│ └── replacement-value-estimate.pdf
├── insurance coverage
│ └── 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 private documentation, I counsel an mkdocs.yml configuration like the next:
# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
site_name: Housing Documentation
theme:
title: materials
font:
textual content: Atkinson Hyperlegible
code: Supply Code Professional
options:
- navigation.on the spot
- navigation.monitoring
- navigation.sections
- navigation.indexes
- content material.code.copy
- content material.code.annotate
- content material.motion.edit
palette:
# Palette toggle for mild mode
- media: "(prefers-color-scheme: mild)"
scheme: default
toggle:
icon: materials/brightness-7
title: Swap to darkish mode
# Palette toggle for darkish mode
- media: "(prefers-color-scheme: darkish)"
scheme: slate
toggle:
icon: materials/brightness-4
title: Swap to mild mode
repo_url: https://github.com/lukehsiao/instance
repo_name: lukehsiao/instance
edit_uri: edit/major/docs/docs/
plugins:
- glightbox
- search
- git-revision-date-localized:
enable_creation_date: true
markdown_extensions:
- admonition
- toc:
permalink: true
- pymdownx.spotlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences:
custom_fences:
- title: mermaid
class: mermaid
format: !!python/title:pymdownx.superfences.fence_code_format
- attr_list
- md_in_html
- pymdownx.emoji:
emoji_index: !!python/title:materialx.emoji.twemoji
emoji_generator: !!python/title:materialx.emoji.to_svg
- pymdownx.smartsymbols
- pymdownx.betterem
- footnotes
I’d counsel utilizing a codename for the location in fact.
The general public Web doesn’t must know any personally finding data.
Equally, I simply have a robots.txt set to disallow all crawlers.
This configuration additionally assumes you’ve gotten:
mkdocs-git-revision-date-localized-pluginmkdocs-glightboxmkdocs-material
in your necessities.txt.
Native Previews with Simply
You’ll additionally discover a Justfile in my instance tree.
I’m an enormous fan of just as a command runner.
I’ve a goal like the next to serve the docs regionally for previewing:
# Serve docs regionally
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 discovered, creating one...";
python -m venv $VENV_PATH;
supply ${VENV_PATH}bin/activate;
pip set up --upgrade pip;
pip set up -r necessities.txt;
mkdocs serve
else
echo "${VENV_PATH} already discovered.";
supply ${VENV_PATH}bin/activate;
mkdocs serve
fi;
This has been a pleasant quality-of-life enchancment for my household on the subject of having a easy place to search out data.
I’ve an irrigation-system reference web page I used regularly when attempting to know how our system labored.
I love the user-manual reference web page, which collects hyperlinks to PDFs or internet person manuals of the entire home equipment, client electronics, and many others. we use; if I must carry out a routine cleansing of the dishwasher, I’m about 3 clicks from the person guide without having to look or discover mannequin numbers.
Having a pleasant how-to information for turning off the water mains provides a way of safety in an emergency.
I really feel like this provides worth to our dwelling, and look ahead to having the ability to move on this documentation to the following homeowners, so they’ll have all of the solutions to the questions I had.
In fact, it’s extremely unlikely the following homeowners will need such an concerned tech stack.
However even in that case, I can simply share the plain-text markdown recordsdata used to generate the location: it can nonetheless be far higher than nothing.
There are numerous different nice concepts and dialogue on HackerNews!