あなたの家のためのドキュメントを書く
(luke.hsiao.dev)- 初めて住宅を所有する人は、設備、修理履歴、製品モデル、遮断方法のような情報を見つけにくく、家にも技術文書のようなユーザーマニュアルが必要だと考えている
- 家の文書はDiátaxisのように、チュートリアル、ハウツーガイド、技術リファレンス、解説に分けると、質問の性質に合わせて整理しやすい
- 4種類の文書に変更ログを加えると、配管修理、灌漑システムの変更、カーペット設置、リフォームのような作業と費用を追跡できる
- 実装は手書きのバインダーやGoogle Docのように単純でもよいが、この事例ではAstro Starlight、gitリポジトリ、Cloudflare Pagesで検索可能なドキュメントサイトを構築している
- 家族は必要な情報を一か所で見つけられ、次の所有者にはMarkdown原本だけを渡しても、記録がまったくない状態よりはるかによい
家にもユーザーマニュアルが必要
- 初めて家を所有する過程では、家の基本情報をすぐ確認できない場面がよくある
- 実際に必要だった質問は次のとおり
- カーペットはいつ設置されたのか
- 水道の元栓をどう閉めるのか
- 灌漑システムがどう構成されているのか
- スプリンクラーヘッドがどこにあるのか
- 食器洗い機のモデルとユーザーマニュアルは何か
- なぜ水圧が高いのか
- 下水管理を担当する会社はどこか
- 家の中の電気回路がどう分かれているのか
- ネットワークケーブル配線があるのか
- 塗料の色は正確に何か
- HVACフィルターはどのモデルを買えばよいのか
- ほとんどの質問には答えがなかったか、自分で調べてリバースエンジニアリングする必要があった
- こうした情報を集めておけば、優れたソフトウェア文書のように、家族が必要なときに参照できる知識ベースになる
Diátaxisで家の文書を構造化する
- 家の文書にも技術文書フレームワークのDiátaxisを適用できる
- Diátaxisは文書を4つのモードに分ける
- チュートリアル
- ハウツーガイド
- 技術リファレンス
- 解説
- 家に関する質問もこの分類に沿って配置すれば、「何をすべきか」と「なぜそうなのか」を分けて探しやすくなる
変更ログで家の履歴を残す
- Diátaxisの4つの分類だけでは、時間とともに変わる家の状態をすべて収めにくいため、変更ログページを追加した
- 過去のすべての質問に答えられなくても、所有期間中に起きた主な変更は記録できる
- 変更ログには次のような項目を残す
- 配管修理と費用
- 灌漑システムのアップグレードと変更
- カーペット設置
- リフォーム
- これにより、「このカーペットはいつ張り替えたのか、必要な面積はいくらだったのか、費用はいくらだったのか」といった質問に、より簡単に答えられる
実装はバインダーからWebサイトまで可能
- 家の文書は、必ずしも複雑な技術スタックで作る必要はない
- 手書きメモを集めたバインダー
- Google Doc
- 短い動画を集めたYouTubeチャンネル
- 携帯電話から検索できるWebサイト
- この家の文書サイトはAstro Starlightで実装されている
- 家専用のgitリポジトリに文書を保存し、Cloudflare Pagesで自動ビルドとデプロイを構成している
- 同じgitリポジトリは、家に関連するほかの重要文書を保管する場所としても使われている
リポジトリに一緒に置ける資料
- 提示されたディレクトリ構成は、家の文書リポジトリに含められる資料の範囲を示している
- リポジトリには次のようなファイルを一緒に置ける
- 契約書とクロージング書類
- 間取り図、オフィス図面、庭のワイヤーフレームのようなダイアグラム
- Astro Starlightベースの文書サイトのファイル
- 金融書類
- ゲストガイドとWi-Fi案内
- 住宅検査報告書
- 保険証券
- 固定資産税関連文書
- インターネット契約関連文書
- 文書サイト内部には、変更ログ、ガイド、紹介、参照文書といった構成を入れられる
家族と次の所有者に残る価値
- 家の文書は家族が情報を探す単一の場所となり、生活の質を高める
- 灌漑システムの参照ページは、システムの動作方式を理解するときによく活用される
- ユーザーマニュアルの参照ページは、家電や電子機器のPDFまたはWebベースのマニュアルリンクをまとめている
- 食器洗い機の定期清掃が必要なとき、モデル番号をもう一度探したり検索したりせず、数回のクリックでマニュアルにアクセスできる
- 水道の元栓を閉める方法のガイドは、緊急時に安心感を与える
- 変更ログは、特定の作業をいつ行い、いくらかかったかを確認しやすくする
- 次の所有者が複雑な技術スタックを望まなくても、サイト生成に使ったplain-text Markdownファイルだけを共有すれば、まったく記録がないよりはるかによい
1件のコメント
Hacker News のコメント
友人に実際にあった話。古い家に住みながら、パンデミック中ずっと終わりのない修繕プロジェクトを続けていて、夜ごと作業しながら人とつながろうとして、よくリフォームのライブ配信をしていた。
ある日、浴室の壁を壊していたら、壁の間からメモ付きのクリップボードを見つけ、読み始めた途端に泣き出した。1970年代に書かれた配線・設備の一覧で、最初のページには「修理は大変で、ときに孤独なものだが、続けてほしい。いつかそれだけの価値があったと思える」といったメモがあったという。
パンデミック中でも特に孤独だった時期に、50年前の誰かが残した文書と励ましが、まさに必要な瞬間に見つかったわけで、本当に美しい瞬間だった。
カリフォルニアに移った家族と、オクラホマ側に残った家族との間の、温かく純朴な手紙で、叔父はその手紙を読むたびに胸が詰まるという。
アメリ では、ダイアナ元皇太子妃の死の知らせを聞いて落とした香水瓶の栓が壁のタイルに当たり、何十年も前にそのアパートに住んでいた少年の幼少期の品々が入った金属箱を見つける。
https://en.wikipedia.org/wiki/Am%C3%A9lie
マルコヴィッチの穴 では、クレイグが書類整理中に小さな隠し扉を見つけ、トンネルを這って進むと俳優ジョン・マルコヴィッチの意識の中に入る。
https://en.wikipedia.org/wiki/Being_John_Malkovich
A Ghost Story では、「M」と表記される女性が、ミュージシャンの夫「C」に、子どもの頃は頻繁に引っ越していて、住む先々に小さなメモを隠していたと話す。
https://en.wikipedia.org/wiki/A_Ghost_Story
家全体が解体と再建の間にあるあいだ、2×2メートルのいちばん小さな部屋だけを完璧に整えて避難所にし、その部屋のおかげで正気を保てた。
床根太の大半が崩れたり腐ったりしていて交換が必要で、一時は屋根と壁の支柱だけが残った空洞のような状態だった。いっそ全部更地にして新築したほうが早くてよかっただろうが、外観は屋根面に傾斜窓を一つ追加した以外、見た目の変更なしで維持すると決めていた。
その後、別の家で大きな工事をさらに2回したが、こういう作業への情熱はもうほとんど底をついた。
前の家では何年もスマートホーム自動化をしていて、すべてについての明確な手順、アップグレードの領収書、保証書、アプリダウンロード用のQRコード、敷地図、間取り図、修理業者の連絡先一覧まで入れたバインダーを作っておいた。
水道の止め方、屋外水栓やスプリンクラーの遮断、デバイスのペアリングといったことも短いYouTube動画にして、何十時間も費やし、家を「温かく引き継ぐ」という達成感があった。
ところが新しい所有者は2年後に家を売り、物件写真を見るとスマートホーム機器の大半を取り外し、雑にリフォームしていた。YouTube動画の再生回数も0で、渡したバインダーを見た可能性もほとんどなさそうだった。
もう二度と家のドキュメント化にあれほど多くの労力をかけるつもりはなく、今は自分が何をしたか分かる程度の文書だけ残している。
実際、「世界に一つだけ」と宣伝されるものは買わない。見た目はよくても、処分が面倒だと分かっているからだ。
派手で立派な設備は価値を足すのではなく、むしろ下げると思っている。撤去する作業が増えるからで、むしろ基本的なIKEAのキッチンがある家のほうが交換もしやすく、場合によってはそのまま使いやすい。
見つかった不具合だけでなく、推奨される修理、継続的なメンテナンス予定、水道の止水位置の写真、動画数本、下水管の内視鏡映像まで含む数百ページの資料だった。
自分が追加・変更した内容を更新していたが、売る段になったら、また検査を依頼するほうが簡単だろうと思っている。ただしスマートデバイスはなく、もしあったなら費用が上乗せされたかもしれない。
ドアがロックされたり侵入者が入ってきたり、旅行中に暖房が何週間も過熱・低温になったりするかもしれないと考え、そもそも関わりたくないと思っている。
単純な浮き式の表示器でも暮らせるだろうが、高精度の静水圧センサー、esp32、influxdb、grafana、spring、keycloak、AWSで動かすmysqlを使わない理由はなかった。
ただ、家を売ることになったらサポートの電話を受けたくないので、おそらく自分で撤去すると思う。
自分も引き継いだスマートホーム機器はたいてい取り外すか、少なくともオープンソースファームウェアで再フラッシュする可能性が高い。
それから学んだ重要な原則は、Wi-Fi、ゲートウェイ、HomeAssistant、一部のセンサーが死んでも、家はただの家のように正常に動作すべきだということだ。
文書を作っても結局捨てられたという話は多いが、反対の例もある
離婚後に空き家になっていた家を買い、前の所有者2人はすでに数か月前に引っ越していたので、ほとんど仲介業者とだけやり取りした
家の中には「新居おめでとうございます」のカード、スパークリングワイン1本、そして家に関するすべてが入ったバインダーがあった。建築図面、変更箇所を反映した最新図面、すべてのケーブルと接続位置、機器のマニュアル・請求書・保証書、庭の植物配置の手描き図や外来植物の手入れリンクまで入っていた
前の所有者がここまで整理してくれたおかげで、ケーブル作業やちょっとした工事のたびに正確な図面が大幅に時間を節約してくれて、今でも感謝している
配管と電線がどこを通っているかを部屋ごとにラベル付けし、いつか売ることがあれば引き渡すつもり。施工業者がこうした壁内部の写真セットを標準で提供しない理由が分からないし、実際とても役に立った
いろいろな用途でバインダーを山ほど持っている
2018年に離婚した後、North Seattleの家を売った。2004年に買い、当時はMicrosoftで働いていて、その家で息子を育てた
ピザとパンを焼く8×8×8フィートのレンガ窯も自分で作り、掘削機を1週間借りて家全体の周囲を掘り、深さ12フィートの基礎排水管、20フィートごとの清掃口、2インチのpex水道管、深さ3フィートの1インチpvcスプリンクラー管も入れた。地下室も完全に解体してリモデルした
3インチのバインダーには、スプリンクラー管、基礎排水、重力式再循環システム、電気配線、6か月かけたレンガ窯プロジェクトの写真、必要なら移設する方法まで、すべて入れておいた
家を売るとき、新しい所有者に直接手渡そうと再び飛行機で行き、説明もしたが、特に関心や感謝はなさそうだった
数か月前にSeattleへ戻り、その家で生まれた17歳の息子が訪ねて、外を見て回ってもいいか尋ねたところ、彼らは変な人を見るような目をしたが許可してくれた。戻ってきて言うには、私が一生自分より長く残ると思っていたレンガ窯を撤去してしまっていたそうだ
いつか100年後に子どもたちがその窯で焼いたピザを食べ、誰が作ったのかも知らない、そんな光景を願っていた。それでも次に家を持つことがあれば、また全部を文書化するつもりだ。ただし、誰に売るかはもっと慎重に見ると思う
窯を作って楽しみ、その後で家を売ると決めたのは本人なのに、なぜその後の所有者が家をどう使うかまで決めようとするのか分からない。ピザ窯を自分の記念碑のように残したかったのなら、家を所有し続けるべきだった
こうした考え方は近所を停滞させ、地域住民が街並みや雰囲気を管理しようとするようになる。結局、新築を妨げたり、ペンキの色まで決める規制につながる
歴史的に重要な空間は保存できるが、少数の人にだけ重要な些細なものを多数に押しつける態度は問題だ。逆に、実際に歴史的意味のある場所はただ朽ちるに任せられることもある
https://www.theguardian.com/us-news/2018/mar/30/rosa-parks-h...
新しい所有者が前の所有者の関心を共有するとは期待できない。グルテンフリーかもしれないし、ベーキングにまったく興味がないかもしれない。自分の家族にとって意味のないもののために、庭の64平方フィートを記念碑のように維持してくれると期待するのは難しい
家に愛着を持ち、良い人の手に渡ってほしいと思う気持ちは理解できるが、新しい家族に合わせて変えないだろうと期待すべきではない
ただ、その願いは、家を頻繁に売買される商品として扱うアメリカ式の住文化とはあまり合わない
両親も数年前に家を売り、父はその家が恋しく、新しい所有者がひどい変更をしているとよく言うが、私がその家で育ち、良い時間を過ごしたという事実は変わらない。今、父には新しい家で孫娘と新しい記憶を作る機会がある
実際に故障していたが、ポンプとセンサーを交換し、きれいに手入れして8年間よく楽しんだ。家を売るとき、買い手には不要なら私たちが新居へ移す交渉も可能だと伝えたが、何の返事もなく家を買った
近所の人から聞いたところ、引っ越してくるなりホットタブを壊して処分場へ送ったそうだ。自分の家なのは確かだが、あまりにも無駄遣いのひどい人もいる
引き継がれた文書が大切にされなかったという話もいくつか見かけるが、別の見方もある。最初の家として手を入れる必要のある家を買ったのだが、前の住人は亡くなった親で、残されていたのは家電のマニュアルが入ったビニール袋、古い領収書、そして何より重要な修理・交換履歴表だった
日付、何が更新されたか、費用はいくらだったかが書かれていて、エアコンやボイラーがどれくらい古いのか、地下室のリフォームがいつだったのか、予備寝室のカーペットをどれだけ注文したのかを推測せずに済んだ。初めての住宅所有者として本当に大きな助けになり、とても感謝している
ボイラーには設置日とメンテナンス日をマジックで書いておき、主排水管には最後に清掃した時期、作業者、詰まった場所を書いておく
産業用ラベルプリンターがあれば、こうした作業は楽になる
とても大人びた、珍しいことのように感じていたが、思ったより一般的なことなのかもしれない
家を建てるとき、石膏ボードを張る前と張った後にMatterportスキャンをしておいたが、これは自分がした中で最高の判断だった。壁を見るX線の視界のような感じだ
配線がどこを通っているか、テレビを取り付けるとき窓の間にスタッドが何本あるか、電気・冷暖房・配管に関するさまざまな問題を確認するときに役立つ。最初は毎週使っていたし、落ち着いた今でも2か月に1回くらい使っている
Dymo Rhino 5200のケーブルラベラーと熱収縮チューブもおすすめ。熱収縮チューブにラベルを印刷して電線に付ければ、どこへ行く線なのか二度と迷わない。車両のワイヤーハーネスにも良い: https://www.youtube.com/watch?v=-LcUQeTzIo4&t=66s
ただし5200をおすすめする: https://www.amazon.com/DYMO-Industrial-RHINO-Label-1755749/d... - アフィリエイトリンクではない
このリンクにはアフィリエイトタグ pmg097-20 が付いている
アフィリエイトリンクではないURLは次のとおり: https://www.amazon.com/DYMO-Authentic-Industrial-RhinoPro-18...
家を買うたびに小さなMoleskineノートを買って、家ノートとして使っている。主要家電の購入、日付とシリアル番号、ブレーカー情報のローカルコピー、リフォームの日付と費用、寸法入りの部屋の図面を書いておく
部屋・モールディング・天井ごとのペイントコードや仕上げも書いておくので、石膏ボードの補修などをするときに、余ったペンキ缶のラベルがめちゃくちゃだと本当に役立つ
引っ越しと購入用の別ノートも作り、融資担当者、不動産仲介業者、検査員、予定、業者、主要日程、入居・退去チェックリスト、保管・廃棄・寄付する物のリスト、支出、役所に提出する書類や住所・電話番号まで入れておいた
これらすべての情報を手元ですぐ取り出せるというのは、かなり強力だ
RVを持っているが、シャシー用の分厚いマニュアル1冊と、工場で取り付けられたすべての機器用のマニュアル1冊が一緒に付いてきた。最初の所有者ではなく、几帳面な軍人である兄が、RVに取り付けたすべての家電と装置の文書を残してくれていた
自分が所有するようになってからその文書にずっと感謝しており、自分もWi-Fi、ネットワーク、工具小屋、昇降デスク、オーブン、配管などについて同じように文書化した
ここ3年ほどは同じ原則を家にも適用し、家の「シャシー」用と家の中の機器用に、分厚いリングバインダーを2冊維持している
インターネットのリセット方法、給湯器の「再起動」方法、エアコンフィルターの交換方法、必要なフィルターの型番、次の所有者と自分自身のためにエアコンに還気口がない理由まで書いている。汚水管の一部が崩れて交換したメンテナンス履歴、掃除口へのアクセス方法、壁の中の電線経路、きちんとラベル付けしたブレーカー、壁ごとのペイントコードも含めている
まずOneNoteに書いて検索できるようにし、その後、区域ごとのセクションがある3穴バインダーに入れる。一度に海を沸かそうとせず、段階的にやれば長くはかからず、何年にもわたってありがたみを感じる。家は、チームが開発したソフトウェアと違って、そんなに早く変わりもしない
本当に良い
オンラインで空欄を埋めるとPDFを生成してくれる方式でよい
素晴らしい助言で、家族の中でこうしたことを主に処理する人が自分なら、予期せぬ死亡や判断能力を失う状態に備える良い方法だ
ただし、ツールや媒体は普通の人が慣れているものを使うべきだ。読むべき人は、gitをLarry the Cable Guyの「git ’er done!」くらいにしか知らないと想定すべきだ
食洗機のマニュアルと輸送用ボルトは、機器の上にテープで貼っておけば十分だ。暖房のようなものは、配管にラミネートした紙を1枚貼っておけばよい
デジタルが好きなら、共有オンラインフォルダに .docx 文書を入れておく程度のほうがよく、40年後でも開いて編集できるツールを見つけられるだろう
ある人にとってはデジタルスタックを作ること自体が目的なのだろうが、数十年もつ文書化というのは信じがたい
たとえば我が家の分電盤にはブレーカーのラベルがマジックで書かれており、家電の注意点やフィルターサイズも現場にメモしてある。情報が必要な場所ですぐ見え、削除されたり有料の壁の向こうに隠れたりしない
技術業界の人たちは、時々物事を複雑にしすぎる
私は自分が育った家に住んでいます。父が増築した2階を自分で設計しました。
父は私には決して分からない形でこの家の骨組みを把握していて、今は50マイル離れた場所に住んでいますが、今でも家に関する非常に頼りになる情報源です。
数年前、2階のオフィスにCat5を引きたかったとき、「その角の床に穴を開けるだけでいい。2階から地下室まで続く空洞がある」と言われ、実際にその通りでした。
私が欲しいのは、父の頭の中にある図面です。
今では何か作業をしようとするとき、骨組みがどうなっているか、給水管・排水管・電線がどこを通っているかを正確に分かるので、とても役に立っています。
おそらくそういうことを尋ねられるたびに、父は内心でぱっと明るくなるのでしょう。