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.
在研究我的一些问题时，我发现我最喜欢的技术文档框架 Diátaxis 在这里非常适用。

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 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.
在介绍这部分内容之前，我想说的是，我的实施方案几乎可以肯定过于复杂。你的可能是一个装有笔记的活页夹。或者是谷歌文档。又或者是一个YouTube频道，里面有很多短视频。我个人喜欢有一个网站，可以在任何设备上调出并搜索。

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.
因此，为了实现文档网站本身，我是 Material for Mkdocs 的忠实粉丝。我为自己的房子创建了一个 git 仓库，用来存储这些文档（通过 Netlify 自动构建和部署）。此外，这个 git 仓库还可以方便地存储其他与房子相关的重要文件。

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 Mkdocs 配置

For my personal documentation, I suggest an mkdocs.yml configuration like the following:
对于我个人的文档，我建议使用 mkdocs.yml 这样的配置：

# 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.
当然，我建议使用一个网站代号。公共互联网不需要知道任何个人定位信息。同样，我只是将 robots.txt 设置为禁止所有爬虫。

This configuration also assumes you have:
此配置还假定您拥有

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

in your requirements.txt.  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:
你还会在我的示例 tree 中注意到一个 Justfile 。我非常喜欢将其作为命令运行程序。我有一个类似下面的目标，用于在本地预览文档：

# 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.
这对我的家人来说是一个很好的生活质量提升，因为他们可以在一个简单的地方查找信息。我有一个灌溉系统参考页面，在我试图了解我们的系统如何工作时经常使用。我喜欢用户手册参考页面，它收集了我们使用的所有电器、消费电子产品等的 PDF 或网络用户手册链接；如果我需要对洗碗机进行例行清洁，我只需点击 3 次就能找到用户手册，而无需搜索或查找型号。如果有一本关于如何关闭自来水管的指南，在紧急情况下会更有安全感。

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.
我觉得这为我们的家增添了价值，并期待着能将这些文件传给下一任房主，这样他们就能得到我所遇到问题的所有答案。当然，下一任房主也不太可能想要这么多技术资料。但即使在这种情况下，我也可以只分享用于生成网站的纯文本 markdown 文件：这样总比什么都没有强。

Comments on HN 对 HN 的评论

There are many other great ideas and discussion on HackerNews!
HackerNews 上还有许多其他好主意和讨论！