家のための文書作成

Technical Documentation for Your House: A User Manual for Homeowners

家を購入した初めてのホームオーナーとして、さまざまなシナリオに関する参照資料があればいいなと思うことが何度もありました。

エンジニアとして、私はこれらの質問に答えるために常にドキュメントを作成し、他のチームメンバーが参照できる知識ベースを構築しています。

これは住宅にも当てはまると思います。

初めてのホームオーナーとして、私は家についてたくさんの質問を抱えています。

実際の例をいくつか紹介します。

残念なことに、これらの質問のほとんどに対しては、答えがなかったり、直接調査やリバースエンジニアリングが必要でした。

これらの質問をまとめるにつれて、私が実際に求めているものは、ユーザーマニュアルのようなものであることに気付きました。

私は、良いソフトウェアが提供するような、良質な技術ドキュメンテーションが欲しかったのです。

そこで、ここに住んでいる間に、私自身でそれを作成し始めました。

私の質問のいくつかを見てみると、私のお気に入りの技術ドキュメンテーションフレームワークであるDiátaxisがここでもうまく機能することがわかりました。

ご存知ない方のために、このフレームワークはドキュメントをチュートリアル、ハウツーガイド、技術リファレンス、および説明の4つのモードに整理することを提案しています。

ドキュメントの4つのモード

この4つのカテゴリに加えて、重要なページも追加します。それは変更ログです。

過去の質問には答えられませんが、少なくとも私の所有権の間に重要な変更の記録を残すことができます。

このページでは、配管修理(およびその費用)、散水システムのアップグレード/変更、カーペットの設置、リモデリングなど、家の主要な変更をすべて記録しています。

これにより、「このカーペットはいつリニューアルされ、どれくらいの面積が必要で、いくらかかったのか」といった質問に簡単に答えることができます。

このセクションを始める前に、私の実装はほとんど確実に複雑すぎると言っておきます。

あなたの場合は、メモのバインダーかもしれません。

Googleドキュメントかもしれません。

短いビデオがたくさんあるYouTubeチャンネルかもしれません。

私個人的には、どのデバイスでも引き出しや検索ができるウェブサイトを持つことが好きです。

したがって、ドキュメントサイト自体の実装に関しては、Material for Mkdocsが大好きです。

私は自分の家のためにgitリポジトリを作成し、このドキュメントを保存しています(Netlifyを介して自動的にビルドおよびデプロイされます)。

さらに、このgitリポジトリは他の重要な家に関連する文書を保存する便利な場所としても機能します。

以下は例のディレクトリ構造です(実際のものではありませんが、説明用です)。

私の個人的なドキュメントについては、次のようなmkdocs.ymlの設定をおすすめします:

“`
site_name: My House
theme:
name: material
custom_dir: material
palette:
primary: ‘blue-grey’
accent: ‘blue’
nav:
– Home: index.md
– Tutorials: tutorials.md
– How-To Guides: how-to-guides.md
– Technical Reference: technical-reference.md
– Explanations: explanations.md
– Changelog: changelog.md
“`

もちろん、サイトのためにコードネームを使用することをお勧めします。

一般のインターネットには、個人を特定する情報は必要ありません。

同様に、ロボット.txtはすべてのクローラーを拒否するように設定されています。

この設定では、requirements.txtに次の内容が含まれていることも前提としています。

私の例のツリーにはJustfileもあります。

私は単にコマンドランナーとしてのjustが大好きです。

次のようなターゲットを持って、プレビュー用にローカルでドキュメントを提供しています。

“`
serve:
mkdocs serve
“`

このドキュメントを簡単に見つける場所があることは、私の家族にとって生活の質の向上につながりました。

私は、散水システムがどのように機能するかを理解しようとするときに頻繁に使用する散水システムのリファレンスページがあります。

ユーザーマニュアルリファレンスページも大好きで、使用しているすべての家電製品や消費電子機器のPDFやWebユーザーマニュアルへのリンクを集めています。例えば、食洗機の定期的なクリーニングを行う必要がある場合、モデル番号を検索したり見つける必要なく、ユーザーマニュアルまで3回のクリックでアクセスできます。

緊急時には、水道メインのシャットオフ方法に関するわかりやすいハウツーガイドが安心感をもたらします。

これにより、私たちの家に価値が追加され、私が抱えた質問のすべての答えを次の所有者に引き継ぐことができることを楽しみにしています。

HackerNewsには他にもたくさんの素晴らしいアイデアがあります!

前回の投稿で、Rustプロジェクトがユーザーに対して行うことができる最も重要なことは、AsyncIteratorを安定化させることだと述べました。具体的には、標準ライブラリで既に存在するインターフェースを指しており、それはpoll_nextというメソッドを使用しています。理想的には、これは…

最大のテック企業は、多くのエンジニアを雇用しています。2021年、マイクロソフトは10万人以上のソフトウェアエンジニアを雇用していました。それは私にとって信じられないほどの規模です。私が育った郡全体の人口とほぼ同じです。彼らは多くのエンジニアに給与を支払っています。…

WebコンポーネントはJavaScriptフレームワークの結合を劇的に緩和することができます。それを証明するために、ちょっとクレイジーなことをやってみましょう。異なるJavaScriptフレームワークで書かれたすべてのコンポーネントでアプリを構築してみます。

Generated by openring-rs

Last Updated: 2023-11-28

注意

  • この記事はAI(gpt-3.5-turbo)によって自動生成されたものです。
  • この記事はHackerNewsに掲載された下記の記事を元に作成されています。
    Writing documentation for your house
  • 自動生成された記事の内容に問題があると思われる場合にはコメント欄にてご連絡ください。

コメントする