ドキュメント：技術ドキュメンテーションの考え方

kawasin73 commented 6 years ago

作成したソフトウェアのドキュメントを作成する上での考え方をまとめる

具体的な着目点や記載する項目については #18 にまとめている

kawasin73 commented 6 years ago

ドキュメントで重要なこと

kawasin73 commented 6 years ago

制約や制限の項目をどの部分に記載するか

設計の根幹に関わる制約は概要や対象プラットフォームなどに記載（例えば、epoll を利用するため、Linux カーネル 2.6 以降、glibc バージョン 2.3.2 以降を対象とする等）
制約 や 制限 は基本的に特定の項目に密接に関連しているので、全体としてまとめるよりも関連性の高い箇所に記載するとわかりやすい

kawasin73 commented 6 years ago

ドキュメントは上から順に読んでいってわかるように構成する。因果関係は上から下に書いていく
ユーザーが利用する目的に沿ったコンテキストによって1ページの内容が決まる。同じコンテキストのものをまとめて記載し、肥大化する場合は共通するパターンによって分割する
共通するパターンがない場合はそのまま羅列する
基本的には 1 ページに多数の異なる大きなコンテキストが表現されている場合には分割する
出来ること・行うことを記載し、読み手が疑問を感じる部分や明記することが難しい部分、開発コストの観点からそのようになってしまった部分等については、注釈や補足情報として記載する

kawasin73 commented 6 years ago

レイヤー毎に何を行うものなのか、レイヤー間の連携はどのようにされるのか、どのように設計されているのか。
- 対象レイヤーはどのようなソフトウェア・コンポーネントで構成されているのか。
- コンポーネント毎にどのような役割を持ち、コンポーネント間はどのように連携されるのか、どのように設計されているのか。
- コンポーネントまたは機能毎の制約や想定される課題（消費メモリの肥大化、処理の遅延、どのような障害パターンが存在するか、etc）、要求仕様上解決不可能な課題と設計上解決出来てない課題の切り分け、推奨される解決手法の提案。
- どのような障害発生パターンがあり、その際にどのような挙動になるのか。障害設計について。

最小構成単位、必須のハードウェア及びプラットフォーム要件、etc
特権的機能を利用するため root 権限が必須といったことから、特定ファイルが存在しなければ起動しない等の制約に関する内容
複数台構成の方法、推奨される構成方法、問題のある構成方法等
ダウンタイムは発生するのか。
ダウンタイムとは（一般論ではなく本設計に置いて）何を指しているのか。
- どのようなケースにおいて発生するのか。
- 特定ケースにおいてダウンタイムが予測可能であれば、どのように予測されるのか。
障害発生時の運用手法、復旧方法

kawasin73 commented 6 years ago

ドキュメンテーションで気をつけること

kawasin73 commented 6 years ago

やらないことは書かない。する必要のないことは書かない（インターネットへのアクセスは必要ないなど）。必要になることだけ書く。

シェルの例は $ か # を先頭につける $ は一般ユーザ # はルートユーザを表す

$ sudo service start nginx

# service start nginx

kawasin73 commented 5 years ago

ルー語は使わない。なるべく日本語に翻訳する。アルファベットだけを並べると詰まった感じがする。

kawasin73 / knowledge