やったこと 実践Next JS 2章 Server Component とレンダリング 読了 学んだこと Server Component と Client Component Server Component とは サーバーサイドでのみ実行されるコンポーネント。 同期/非同期関数 のどちらでも記述できる。 AppRouter 内で実装される React コンポーネントは、デフォルトでは全てのコンポーネントが Server Component として扱われる。 Client 側で実行したくない処理（DB からデータを取得する処理など）は当然として、 ブラウザとサーバー、どちらで実行しても問題ないものは、 とりあえず Server Component として実装すると吉（要件によって異なる）。 Client Component とは クライアントサイドで実行されるコンポーネント。 use client と明示することで、 Client Component として扱われる。 Client Component として実装するユースケースは、主に以下がある。 alert のような、ブラウザの機能を使用するコンポーネント イベントハンドラによる動的処理を実現したいコンポーネント 補足 RSC は React Server Component の略 Server Component と SSR は別物 参考記事: https://postd.cc/how-react-server-components-work/#01 ハイドレーションとは 事前に生成された HTML に対してイベントハンドラをアタッチしていく処理 画面の初期表示の際に、サーバーから取得したデータを用いて画面の基本的な構造を構築します その後、フロントエンドの JavaScript やフレームワークによって、画面に追加のデータやコンポーネントがダイナミックに挿入されます ユーザーが画面を操作すると、追加のデータやコンポーネントがサーバーから取得され、画面に反映されます Next JS のキャッシュ NextJS では、 独自拡張した fetch 関数を使用することで、キャッシュ機能を使用できる。 {cache: "no-store"} キャッシュしない 頻繁に更新されるデータなど、キャッシュしたくないデータに対して使用 {cache: "force-cache"} キャッシュする 更新される見込みがないデータに対して使用 {next: {revalidate: wait_second } wait_second で指定した時間だけキャッシュする 更新頻度がある程度わかっているデータや、正確性が求められない（≒大雑把でよい）データに対して使用 ISR (Incremental Static Regeneration) とも密接に関係 デフォルトでは、 {cache: force-cache} 、つまりキャッシュする。 キャッシュデータは、 .next/cache/fetch-cache に保存される。 Route のレンダリング Routeのレンダリングには、動的レンダリングと静的レンダリングの二種類が存在する。 動的レンダリング ... リクエストの度に、HTMLをレンダリングするレンダリング方針 静的レンダリング ... 事前にHTMLをレンダリングしておき、リクエストに備えるレンダリング方針 これらは、ビルド時にNextJS側で判断してくれる。 Next JSのキャッシュ機能を活かした高速配信を実現するためにも、静的レンダリング+CDN という構成が望ましい。 Next JSでも、まずは静的レンダリングを試みて、ダメだったら動的レンダリングに切り替わる ... という挙動をする。 動的レンダリングの要因は以下のとおり。 動的データ取得の使用 HTTPリクエストを参照するような関数の使用 Dynamic Segment の使用 用語整理 Client Side Rendering まっさらな HTML ファイルを用意。 JS で DOM を生成し、HTML にアタッチしていく。 以下のデメリットを抱える。 DOM の生成 & アタッチが完了するまで、画面に何も表示されない js ファイルのサイズ次第で、js ファイルのダウンロード時間が無視できないほど長くなる SEO で不利 上記デメリットは、Server Side Rendering によってある程度軽減できる。 Server Side Rendering 「DOM 生成 & HTML へアタッチ処理」の一部分をサーバー側で実行する。 つまり、サーバー側でレンダリング処理の一部を行い、結果をクライアントへ配信する。 Client Side Rendering のデメリットをある程度軽減できる。 Static Site Generator サーバーへのリクエストに応じて、事前に生成しておいた HTML ファイルを配信する。 動的な JSON ファイル Astro とか ハイドレーション 事前に生成された HTML に対してイベントハンドラをアタッチしていく処理。 レンダリングの種類 Full CSR... まっさらな HTML & JS CSR with Prerendering... 骨格レベルの HTML は事前にレンダリング (静的 HTML)) & JS Dynamic HTML & JS/DOM... 参考 https://qiita.com/akashixi/items/84cd79e090a283bb8c67 https://zenn.dev/dozo13189/articles/07e96c182afa46

やったこと 書籍「エンジニアのためのドキュメントライティング」 PART3 (7,8,9,10,11章) 読了 学んだこと 7章 ドキュメントの公開 最初から完璧を求めない。 リリース後、フィードバックに基づいて更新を繰り返すつもりでいること。 ドキュメントの公開に当たって、やるべきこと コンテンツリリースプロセスの構築 公開タイムラインの作成 公開の最終決定と承認 読み手へのコンテンツの告知 コンテンツリリースプロセスの構築 リリースするまでの計画（≒流れ）を予め用意しておく。 以下の質問に答えることで、計画に必要な情報を収集できる。 コンテンツをいつ公開するか？ 最終レビューと公開の責任者は誰か？ コンテンツをどこで公開するか？ コンテンツを公開するために、追加で必要となるソフトウェアツールは？ 新しいコンテンツをどのように発表するか？ 公開タイムラインの作成 ドキュメント公開に向けて必要なタスクについて、作業計画（=> 公開タイムライン）を作成する。 ◆公開タイムライン 公開に向けて必要不可欠なタスクがすべて揃っていること、 および、タスクの完了に向けて十分な時間があることを確認するための方法の一つ イメージはガントチャート。 基本的には、ドキュメントは、対応するアプリケーションと同時に公開する。 そのため、公開タイムラインのタスクには、ソフトウェアのリリース作業情報も含めると良い。 公開の最終決定と承認 ドキュメントのリリース・差し止めを判断する最高責任者を 一人任命する。 その人物にリリース・差し止めを判定してもらう。 差し止めの主な基準は、「ドキュメントがユーザーにとって有害かどうか」 コードレビューと同じタイミングでドキュメントのレビューを挟む。 こうすると、リリースする機能に関するドキュメントもレビュー済みであることを確信できる。 読み手へのコンテンツの告知 ドキュメントを公開しても、ユーザーに読まれなければ意味がない。 ユーザーに合わせて、適した公開方法を選択すること。 そして、読み手の取って最も合理的なスタート地点に、リリースしたドキュメントのリンクを貼ること。 社内向けだと、社内でよく使用されるWikiなど ソースコードやエンドポイントを使用する外部の開発者であれば、リポジトリの中に含めるとよさそう サービス利用者であれば、少なくともソフトウェアの外部にドキュメントを配置すること ◇◆◇◆◇ コンテンツのリリースに慣れてきたら、改善できそうな箇所が無いか探してみること。 公開プロセスの自動化も、良い選択肢。 ただし、最初は作りこみ過ぎず、最も単純な個所から取り組むと良い。 8章 フィードバックの収集と組み込み リリースしたドキュメントを改善するために、ユーザーからフィードバックを受け取る。 フィードバックチャンネルの作成 フィードバックからアクションを決定 フィードバックのトリアージ フィードバックチャンネルの作成 ユーザー数、ユーザーの属性に応じて、フィードバックチャンネルを設ける。 ドキュメントページからフィードバックを直接受け取る サポートチケットをモニタリングする ドキュメントに対する感情を測定する 「このページは役立ちましたか？」「「はい」、「いいえ」」のアンケート 感情は、コンテキストの影響を受けやすい トラブルシューティングページは、低評価をつけやすい傾向にある ... など ユーザーサーベイを作成する ユーザー会を設立する ユーザーの目的は、ドキュメントを読んで目的を達成すること。 フィードバックを送信する事ではない。 ユーザーの労力が少なくすることを念頭に、色々なチャンネルを検討すること。 フィードバックからアクションを決定 フィードバック情報を基に、ユーザーの目的達成を妨げる障害を排除する（または、目的達成を更に助ける）アクションを決定する。 フィードバックのトリアージ フィードバックのアクションに対して、優先順位をつけて対応する。 優先順位をつける際、以下の評価項目を考えると良い。 そもそもドキュメントに関連する課題であるか？ ドキュメントに関係ない課題であれば、関連部署にエスカレーションする ドキュメントの改善に向けて、アクションに落とし込めるか？ 再現可能？ 「全部書き直してほしい」とか「役に立たない」のように、曖昧で範囲が広すぎると、アクションに落とし込めない 課題はどれぐらい重要か？ アクションを実行し、課題に対応したら、フィードバックを送ってくれたユーザーに感謝を伝えると良い。 9章 ドキュメントの品質測定 目的にかなっているドキュメントこそ、優れたドキュメント。 ドキュメントの目的は、以下の二点。 ユーザー特定の行動を促進すること 組織のゴールを達成すること 上記二点に合わせて、ドキュメントの品質を次の二つの基本的なカテゴリに分類できる。 機能品質 : ドキュメントの目的やゴールが達成されているかどうか 構造品質 : ドキュメントが上手く構成されているか、読みやすいか 機能品質 ドキュメントが、役割（≒ユーザーが目的を達成すること）をどの程度果たしているかを表す指標。 機能品質は、以下のカテゴリに分解できる。 アクセシビリティがあること 難しい文法、語彙を使用しない ユニバーサルデザインを導入している 目的があること 目的に加え、想定読者や読み手が達成できることを書いておくと良い みつけやすいこと 以下を表す指標 どれぐらい簡単に読み手がコンテンツにたどり着けるか どれぐらい簡単にコンテンツ内を読み進めることが出来るか サイト全体における現在地を表示するなど、各ドキュメントに、できるだけ多くのコンテキストを記載すると良い 正確であること 完全であること 以下を満たすこと 読み手が従うべき前提条件がすべて一覧化されている タスク完了に必要なすべてのタスクが載っている 読み手が取るべき次のステップが定義されている 構造品質 ドキュメントをいかに簡単に理解できるかを表す指標。 以下3つのCで定義する。 Clear （明確な） ドキュメントをいかに簡単に理解できるか 難解な専門用語や、不必要に長い言葉を避ける...など Concise （簡潔な） 読み手に関連する情報とゴールに関する情報のみが含まれること 短くてわかりやすいこと =>不要な言葉や不必要なコンセプトは記載しないこと Consistent （一貫している） コンテンツの構造、導入するコンセプト、言葉の選択（≒語彙）がドキュメント全体で同一であること 機能品質と構造品質の優先順位 機能品質の方が重要。 => どれだけうまく構成されていても、読み手が目的を達成できなければ、ドキュメントの存在意義はない。 レビューやメトリクス収集の際も、「機能品質を満たしているか」が重要な観点になる。 なお、レビューやメトリクス収集の際、人間は構造品質に目が行きやすい。 注意すること。 メトリクスを収集して品質向上に役立てる 「目的にかなっているドキュメントこそ、優れたドキュメント」であることを念頭に、収集するメトリクスを決定する。 知りたいこと（質問）に合わせて、収集するメトリクスを決定する。 質問 ドキュメントのメトリクス ドキュメントを読んでいるユーザー数は？ ユニーク訪問者数 最も閲覧されているドキュメントは？ PV数 など 収集したメトリクスを評価する場合、以下の点を念頭に置くこと。 計画を作る なぜ測定したいのか？ その情報を使って何をするのか？ その努力で、どのように組織のゴールを前に進めることが出来るのか？ 基準値を確立する 比較できるようにする（比較できなければ、評価できない） コンテキストを検討する ドキュメントのコンテキスト次第で、メトリクスの解釈を誤る可能性がある 例） PV数増加 => 利用者急増？ => 実はエラーページのPV数が大きく増加 => 読み手が問題を抱えている可能性が高い 複数のメトリクスを組み合わせることで、より詳細な問題発見につながる可能性がある。 この辺りは、監視と同じ。 評価の際は、フィードバック情報も参考にすると良い。 具体的な問題について、より多くの背景情報が得られる可能性がある。 10章 ドキュメントの構成 サービスの成長に伴い、ドキュメントも増加する。 ドキュメントが増加していくと、未整理、または不適切な配置のドキュメントも現れる。 未整理、不適切な配置のドキュメントを整理し、構成を組み立てなおす必要がある。 "ドキュメントに適用する構成上の組み立て" を、 ドキュメントの情報アーキテクチャと呼ぶ。 ドキュメント構成のゴールは、以下の通り。 ーザーが必要な情報を見つけるのに役立ち、 管理者が長期間にわたって保守・スケールで切るような、 コンテンツにとって最適な構成上の組み立てをつくること。 イメージは、駅や空港の地図。 以下の情報をドキュメントに組み込むことで、読み手が、コンテンツのメンタルモデル（コンテンツ構成のイメージ）を作れるよう支援する。 サイトナビゲーションと構成 ランディングページ ナビゲーションの手がかり また、プロダクトとドキュメントの進化に合わせて、サイトに対するユーザーのメンタルモデルを検証し、改善に努めること。 サイトナビゲーションと構成 サイトナビゲーションは、現在のコンテンツの地図と将来追加されるコンテンツの予定図の両方を示す。 コンテンツ整理の主要な方法は、以下の3つ。 シーケンス（順序構造） 階層（ピラミッド構造） Web （階層構造を持たない、相互リンク構造） 扱う情報に合わせて、上記方法を組み合わせて情報アーキテクチャを構築する。 チュートリアルや手順書はシーケンス、ノウハウ集は相互リンク、ランディングページは階層...など ランディングページ 「最小限の文章量で、適切なコンテンツへとユーザーを誘導する」ことを目的としたページ。 道路上で進行可能な方向を指し示している大きな標識に相当する。 ユーザーにとって、最も重要で関連のある情報は、強調しつつランディングページに乗せると良い。 ランディングページに載せるコンテンツを決める場合、ユーザー調査の結果（1章）と会社の戦略目標は良い参考情報になり得る。 ランディングページがごちゃごちゃしてはならない。 ランディングページに乗せるコンテンツは、ユーザーにとって最も重要である情報に制限すること。 ナビゲーションの手がかり コンテンツのほかの部分と、読み手の現在位置を比較できるような情報。 迷子になりつつある読み手に現在位置を示しつつ、次に向かうべき場所を知るきっかけになる。 ナビゲーションの手がかりには、以下の要素がある。 パンくずリスト 再度ナビゲーション ラベル止めたデータ 「前提条件」、「次のステップ」、「追加の情報」といった、関連情報へのリンク 間違ったページに迷い込んだ読み手向けの脱出口（「ホーム」など） ドキュメント再構成にあたって 以下の質問を投げかけ、既存のコンテンツを評価する。 このページは役立っているか？ このページは最新化されているか？ このページは適切な位置に配置されているか？ 評価に応じて、ドキュメントへの対応を表す、以下のようなラベルを付与しておく。 そのまま 削除する 正確性をレビューする 他のドキュメントと統合する 複数のドキュメントに分割する など 評価後、「ユーザーは欲しがっていたけれど、リストに書いていない情報はあった？」と自問自答し、コンテンツのギャップを探索する。 発見したギャップが小さくなるよう、コンテンツを再構成していく。 特に、再構成に当たって、読み手は以下を期待する。 一貫している 構造に一貫性があり、目的の情報の配置場所が予測しやすい 関連している 目的の達成に役立つ、最も重要なドキュメントをすぐに発見できる 見つけやすくなっている 11章 ドキュメントの保守と非推奨化 ドキュメントに記載された情報が不正確だと、ユーザーはドキュメント、および製品への信頼を失う。 ユーザーが目的を達成できるよう、ドキュメントを保守していく。 保守計画 ドキュメントの保守に当たり、コードとドキュメントの整合が必要。 整合を取るためにも、保守計画を立てる。 コード、およびドキュメントの変更が、ユーザーへ与える影響を分析する。 今回の変更によって、ユーザーにどのような影響があるか？ 今回の変更によって、プロダクトの既存機能に影響があるか？ 既存のドキュメントには、どのような影響があるか？ ユーザーを支援するために、ドキュメントを新規に作る必要があるか？ リリースプロセスの中に、ドキュメントの保守作業を組み込むと、整合を取りやすい。 ドキュメントの変更に責任を持つ、ドキュメントオーナーを明示的に任命し、責任の所在を明確にする。 これにより、ドキュメントが古くなることの防止につながる。 そして、コンテンツの保守を担当している開発者に報いること。 ドキュメントの保守は必要な作業である、「余分な」もしくは「追加」の作業と考えてはならない。 リリースプロセスの計画段階から、ドキュメントの保守工数を見積もりに追加しておくとよさそう 保守の自動化 トイルを根絶する目的で、保守作業を自動化する。 ❓トイルとは プロダクションサービスを動作させることに関係する作業で 手作業で繰り返し行われ、自動化することが可能であり、戦術的で長期的な価値を持たず、 作業量がサービスの成長に比例する傾向を持つ...といった特徴がある。 主な保守作業は以下の通り コンテンツの鮮度確認 コンテンツの最終更新日を確認する 古いドキュメントを発見したら、記述に問題が無いかレビューを行う リンクチェッカー ドキュメントに記載されているリンクが、リンク切れを起こしていないか確認する ツールで十分確認可能 デプロイ前 : CI/CDにリンク検査プロセスを組み込む デプロイ後 : 公開後のドキュメントに対して、クローラーを使用して検査 リンター 誤字脱字、怪しい構文を自動検出・修正する リファレンスドキュメント生成 可能な場面であれば、リファレンスドキュメントを自動生成する => API ドキュメントであれば、OpenAPI書き出しなど ドキュメントの非推奨化 サービスの成長に伴い、コンテンツが非推奨化することは十分あり得る。 誤った情報をユーザーに伝えないためにも、 コンテンツの非推奨化に合わせて、関連ドキュメントにも、コンテンツが非推奨である旨を記載する必要がある。 基本的には、APIを非推奨化するプロセスと同じ要領で、関連ドキュメントも非推奨化する。 今後非推奨となる事項をユーザーに告知する...という方法もある。 以下の方法が考えられる。 リリースのお知らせやリリースノートの中で、非推奨機能の一覧を書きだす ドキュメント内に、非推奨機能の一覧を書きだす ドキュメントの削除 原則として、ドキュメントは、ユーザにとって不要になった時点で削除する。 「不要になった時点」 非推奨APIの移行が完了し、非推奨APIの利用者が0であることを確認できた場合 陳腐化・無関係化したドキュメントが存在し、その修正工数が割に合わない場合 不要な情報が減ると、ドキュメントを探索する読み手は、その分迷子になりにくくなる。 削除の前に、事前にユーザーに知らせるべき。 その際、リリースノートにて、機能削除と併せて告知すると効果的。

やったこと 書籍「エンジニアのためのドキュメントライティング」 PART2 (3,4,5,6章) 読了 学んだこと 3 章 ドキュメントのドラフト 白紙のドキュメントの冒頭に、「読み手、目的、コンテンツパターン」を書くところからスタート。 タイトルを決める 「読み手、目的、コンテンツパターン」が決まると、タイトルを決定できる（特に「目的」は有用）。 タイトルを見た瞬間、ゴールがイメージできるようなフレーズにする そのため、キュメントのゴールは一つに絞ること 複数のゴールが存在する場合、ゴールが一つになるようドキュメントを分割すること アウトラインを作る 読み手が、タイトルに書いたゴールを達成するために、読み手が知っておくべきこと、やるべきことを考え、必要な手順を列挙する。 ゴールを達成するために、ゴールをサブタスクに分割するイメージ 正しいタイミングで、正しい情報を読み手に提供できるよう、アウトラインを修正する。 順序を変える （必要に応じて）項目を追加・削除・変更する 複雑すぎる場合、項目を分割する 以下の質問を自身に投げかけ、アウトラインをレビューする。 追記すべき事前情報や設定情報はあるか？ 飛ばしている手順や、説明が不完全な手順は無いか？ 手順は合理的な順で並んでいるか？ アウトラインに自信が持てたら、アウトラインの項目を肉付けしてく。 流し読みに対応する 大多数の読み手は、必要な情報を求めてドキュメントを流し読みする（F 型）。 流し読みする読み手を想定し、必要な情報を見つけやすくすることは重要。 流し読みする読み手に役立つコンテンツ作りの戦略は、以下の通り。 最も重要な情報を冒頭で述べる ドキュメントのゴールを要約して、タイトルに設定する 大きな文章の塊を分割する 複数の長文ドキュメントを分割する 簡潔さと明確さに向けて努力する 「このコンテンツで読み手のニーズを満たせているか？」と問い、改善に努める ドラフト作成に行き詰ったら 完全主義からの脱却 かけるところから書く 周りの人に、助けを求める 足りないコンテンツを強調する 書けない（重要な情報が欠けているなど）箇所は、TODO, T.B.D. などと書いていったんスルー 確信をもって書ける部分から書いていく 順不同で書く 書けるところから書く メディア（ツールや手法など）を変える ドラフトを完成させる 以下、ドラフト完成のチェックリスト。 [ ] 大見出しはドキュメントのゴールを要約しているか？ [ ] 複数の見出しによってドキュメントは十分に要約されているか？ [ ] ドラフトは最初から最後まで読み手のニーズにこたえているか？ [ ] 情報の流れは読み手に取って理解しやすいものか？ [ ] 何らかのドキュメントパターンやテンプレートに正しく従っているか？ [ ] 全手順が動作することをテストし確かめたか？ 4 章 ドキュメントの編集 ここで言う編集とは、ドキュメントを見て、ユーザーニーズに応えているか確認するプロセス。 レビューや評価といった、分析的なプロセスではない。 編集方法 編集プロセスを一連の複数の周回に分解して、一つの周回で一つの観点に絞って編集すると良い。 編集速度が向上する 開発者向けドキュメントだと、以下の観点で編集を周回すると良い。 技術的な正確さ 観点 指示通りに作業すれば、ドキュメントに記載された結果が得られるか？ 技術的な専門用語、もしくは混乱しやすい用語はあるか？ コードの関数、パラメータ、エンドポイントは正しく命名され、説明されているか？ 手順があれば、指示通り実行して、うまくいくことを確認すること 手順に制約条件があれば明記する事 完全性 観点 TODO, T.B.D. が無いこと コンテンツにギャップが無いか OS 上の制約や情報の有効期限があれば記載する 構成 観点 タイトルと見出しから、何について書かれたドキュメントか明確になっているか？ ドキュメントは、一貫性のある、論理的な方法で構成されているか？ 他のドキュメントに配置すべきセクションは無いか？ テンプレートが存在するならば、テンプレートに従って書かれているか？ 一貫した構成は、予測が可能となり、読み手が適切な部分にたどり着きやすくなる 読み手がコンテンツを読む前後にすべきことが無いか確認する 読み手は、前後のドキュメントを読まず、いきなり特定の章から読み始めることが少なくないため 明確さと簡潔さ 不自然な表現は書き換え、重複情報を削除し、不要な言葉を取り除く コンテンツはできる限り短くし、要点を絞る さしずめ、ドキュメントに対するリファクタリング ドキュメントレビュー 自身でレビューする場合、以下のチェックリストを使用する。 [ ] タイトルが短くて具体的である [ ] 見出しは論理的に並べられており、一貫性がある [ ] ドキュメントの目的が最初の段落で説明されている [ ] 手順はテストされていて動作する [ ] 技術的なコンセプトが説明されている、もしくはリンクされている [ ] テンプレートの構成に従っている [ ] リンクがすべて有効である [ ] 誤字脱字・文法チェックツールが実行されている [ ] グラフィックや画像が明確で有用である [ ] 前提条件や次のステップが定義されている 他のメンバーにレビューを依頼する場合、レビューの観点を伝えること。 構成をレビューしてほしいのか？技術面なのか？明確さと簡潔さを見てほしいのか？ など また、フィードバックの受け取り方も合意しておくこと。 場合によっては、専門家にレビューを依頼する（=>テクニカルレビュー） もらったフィードバックを取り入れる ドキュメントのゴールは、知識を読み手に効果的に伝えること。 フィードバックは、非難ではなく、より効果的に伝える方法を指摘するものだと捉える。 矛盾したフィードバックがある場合、「ユーザーがこのドキュメントを読んで達成したいこと」、つまりはゴールを満たすことに繋がるフィードバックを優先する。 どのみち、全てのフィードバックに対応するのはリソース的にも困難となりやすい 良いフィードバックを提供するためには、以下を守る。 フィードバックの際は、「人」ではなく、「アイデア」に集中する 「あなたが間違っている」ではなく、「この部分が不明確だ」といった具合 批判に続けて、建設的な代替案を出す フィードバックに反応するための時間を確保する また、フィードバックでは素晴らしかった部分を伝えてもよい。 素晴らしい文章を共有することで、他の人がまねできるようになる。 5 章 サンプルコードの組み込み 良いサンプルコードは、文章で説明する以上に多くの情報を読み手に提供できる。 サンプルコードは、一般的に「説明用」と「実行可能なもの」の二種類存在する。 実行可能なサンプルコードは、コピペ（かつ必要に応じて改変）して実行できるコード 説明用のサンプルコードは、読み手の理解向上や、読み手の環境での実行結果を比較する目的で使用するコード 良いサンプルコードの原則 読み手は、サンプルコードが（可能ならコピペしてそのまま）動作することを期待する。 そんな、良いサンプルコードは、以下の原則を満たすべき。 説明されていること サンプルコードのそばに、コードの必要性を説明したコメントが存在すること コードを動かすために必要な前提条件が、全て説明されていること 制約などがあれば、きちんと書くこと 簡潔であること 読み手が必要とする、過不足ない量の情報が提供されていること 明確であること 読み手が期待する言語習慣に従ってサンプルコードが書かれている 読み手が混乱しないよう、複雑なテクニックは避ける 加えて、実行可能なコードは、以下の原則を満たすべき。 利用可能（であり拡張可能）であること パラメータの置き換えが必要な場合、置換用データを説明する 何で置き換えればよいのか一目でわかる変数を使用すること your_password や replace_with_actual_xxx など 信頼できること ペースト可能であり、動作し、余計なことを実行しない サンプルコードの設計 サンプルコードの設計に当たっては、以下の点を留意する。 読み手になじみがあって、最も使われそうな言語を選んで、サンプルコードを作成する 快適さ・理解度合いに幅がある読み手をサポートするため、様々な複雑さのサンプルコードを提供する 初心者向けだと、 hello_world レベル 習熟した読み手向けだと、 特定のユースケースに特化したサンプルコードなど 入門者向けドキュメントと、熟練者向けドキュメントを混同しないよう注意すること コードだと一目でわかるような、一貫したスタイルでサンプルコードを提供する Markdown なら バッククォート がメジャー その他、サンプルコードに関する Tips 実行可能なコードは、動作確認しておくこと 場合によっては、読み手が自由にコードを試せるサンドボックスを提供する 多くのユースケースでは過剰な選択 サンプルコードを自動生成する 背景説明といった文脈が必要な場合、人手によるコメント追加も行うこと 6 章 ビジュアルコンテンツの追加 " 百聞は一見にしかず " 。 ビジュアルコンテンツはドキュメント補助が目的。 ドキュメントの代替にはなり得ない。 ビジュアルコンテンツの目的は、ドキュメントの理解促進であり、これに寄与しない情報は全て邪魔、ぐらいに思っておくこと。 読み手の必要とする情報と、作り手の好みは、異なることが多い ビジュアルコンテンツは、以下の三点を満たすことを常に意識する。 理解容易性 読み手に役立つ情報であること アクセシビリティ 読み手を限定しないこと パフォーマンス ビジュアルコンテンツの掲載によって、ドキュメント表示が遅くなり、読み手の時間を奪わないこと ビジュアルコンテンツも、ドキュメント同様にレビューすること。 その際、上記三点を満たしているかがレビューの観点となる。 ビジュアルコンテンツの例 スクリーンショット 可能なら、画像が表現している情報を、文章でも表現すると良い 加えて、画像が、さも存在しないようなコンテンツ説明文にすると良い ×「メニュー上部にある小さな歯車の画像」 〇「メニュー上部に小さな歯車があります」 コピペが必要になりそうな情報をスクショで提供しないこと 図表 ボックスと矢印 文書単体では説明が難しい、エンティティ間のデータの流れや関係性をわかりやすく描くことが出来る 使用する図形に一貫性を持たせること 必要なら凡例を記載すること フローチャート プロセスをドキュメントに落とし込むことが出来る 使用する図形に一貫性を持たせること スイムレーン 複数のコントリビューター（もしくはアクター）が存在する状況を表現できる 複数のコントリビューター（もしくはアクター）が存在することを除けば、特徴はフローチャートと同じ 図の目的は " 単純化 "。 一つの図で表現するアイデアは、一つに絞ること 場合によっては複数の図に分割すること 図表の要素には、可能なら、読み手の理解を促進するようなラベルを付与すること 色に一貫性を持たせること 基本は、ラベルで情報を伝える 可能なら SVG 形式で画像を公開すること 映像コンテンツには注意 映像コンテンツには、以下の問題点があり、総じて高コスト。 作成には専門知識が必要であり、素人には難しい 修正が困難（≒保守コストが非常に高い） 基本的には、上記問題点によるデメリットが大きい。 数枚の図で大体できないか検討すること。

やったこと 書籍「エンジニアのためのドキュメントライティング」 PART1 (1章、2章) 読了 学んだこと 1章 読み手の理解 ドキュメントは、読み手のためのもの。 まずは、読み手のことを知る必要がある。 「知識の呪い」は、読み手の理解を妨げる。 ❓知識の呪い 「自分が知っていることは、相手も知っている」と思い込むこと。 いくつかのステップを踏むことで、知識の呪いから逃れ、ユーザーを理解することができる。 ユーザーのゴールを特定する 「ドキュメントを読んで、ユーザーが達成したいこと」を突き止め、ゴールとして定める 注意点として、プロダクトのゴールと、ユーザーのゴールは、必ずしも一致しない ユーザーを理解する どんなユーザー（開発者・マネジャーといったロール、技術習熟度など）がドキュメントを読むのか、想定する ユーザー全員のニーズを満たすことは不可能 ビジネスやプロダクトにとって最も重要なユーザーを優先すること 例？）セキュリティ、SRE、開発では、いずれも求められる情報が異なるはず ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する 詳細は後述 わかったことを、ツール（ペルソナ、ストーリー、マップなど）を使ってまとめる フリクションログを使って仮説検証する ユーザーの立場に立って、ユーザーの目的達成を阻害する要因（≒フリクション）を自分で体験する よくあるユースケースを定義し、自分でなぞらえると良い ❓フリクション（ログ） 摩擦や抵抗のこと。 特に、ソフトウェアやサービスをうまく使えなかったことや違和感といった体験を示す。 "フリクションログ" だと、摩擦や抵抗を示す記録。 ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する ドキュメントで答える必要がある（≒ユーザーが疑問に思う事項）のリストを作る。 よくある疑問は、以下の通り。 これは何のプロダクト？ 個のプロダクトが解決する問題は？ どんな機能がある？ 費用はどれぐらいかかる？ どこから始められる？ 出来上がったリストを、「アウトラインの作成」という形でまとめる。 アウトラインが出来上がり次第、「ユーザーは誰か」「ユーザーのゴール」「ユーザーのニーズ（アウトライン）」を検証する。 検証の際は、ユーザーのウォンツ（要望）ではなく、のニーズ（要求）に焦点を当てること。 主な検証方法は以下の通り。 サポートチケットなど、存時の情報リソースを使う インタビュー、アンケートなどで、新しいデータを集める 2章 ドキュメントの計画 ユーザーのニーズに合わせて、コンテンツの種類（手順書、クイックスタートなど）を決定していく。 よく使われるコンテンツタイプは以下の通り。 コードコメント README スタートガイド コンセプトドキュメント 手順書 チュートリアル ハウツーガイド リファレンスガイド トラブルシューティングドキュメント 変更に関するドキュメント リリースノート 質の高いドキュメントを作成するために、ドキュメント作成の計画を立てる。 以下の質問に答えることで、ユーザーにとって適切な情報を絞り込むことが出来る。 対象の読み手は誰か？ プロダクトのローンチから、ユーザーに一番学んでもらいたいことは何か？ 重要度順で考えると、どの機能からリリースされていくか？ ユーザーはローンチに何を期待しているか？ ユーザーがプロダクトや機能を使い始める前に必要な事前知識はあるか？ 何のユースケースをサポートしているか？ ユーザーが躓きそうな既知の課題や、フリクションはあるか？ これらの質問に答えることで、コンテキストを形成できる。 コンテキストが分かってくると、何から作り始めればよいか決められるようになる。 コンテンツのアウトライン作成から、ドキュメント計画を立てると良い。 以下、コンテンツアウトラインの例 タイトル コンテンツのタイプ 簡単な説明 xxx スタートガイド スタートガイド xxxを使うための非常に簡単なデモと他のドキュメントへのリンク xxx yyy機能の解説 コンセプト yyy機能の仕組みの技術説明 認証方法 ハウツーガイド 認証スルタンのステップバイステップ手順 APIリファレンス APIリファレンス API呼び出し方法と構文の一覧 リリースノート l変更履歴 xxxのリリースノート 以下、コンテンツタイプ別の追加情報。 コードコメント コーディング上の意思決定とその背景や、トレードオフを記録することで、読み手である将来の開発者の時間を節約する 過剰なコメントは、保守コストが増大することを念頭に置くこと README 以下の役割を担う 読み手に、システム全体の概要を理解してもらう リポジトリに対するチートシートとして機能する ユーザーが利用する包括的なドキュメントの基礎（ポータル）として機能する より詳細な情報が必要な場合は、重要なサブフォルダに追加情報を配置し、追加情報へのリンクをREADMEに貼る テンプレート スタートガイド 読み手（ユーザー）の立ち上げを支援する より高度（≒専門的・詳細）なコンテンツへ進む前のスタート地点として機能する スタートガイドを書く上で、自身に問うべき質問は以下の通り サービス内容と核となる機能を一番短く説明するなら？ プロダクトをインストールして使うための最も簡単な方法は？ 新規ユーザーが感じる最も重要な疑問は？ サービスを使ってできるすごい事は何か？ コンセプトドキュメント サービスの裏側にある考え方とアイデアの理解を助ける 手順書やチュートリアルの背景を説明する ... といった用途で作成する 実装に関する詳細は、コンセプトドキュメントの領分ではない（手順書などの領分） テンプレート 手順書 具体的には、「チュートリアル」と「ハウツーガイド」が該当する 読み手（開発者）が、特定のゴールを達成する方法を、手順として説明する 以下、手順書作成時のガイド できるだけガイド単体で読めるようにする ユーザーが必要とするすべての行動を1つのページにまとめる 手順数を最低限に絞る ステップが多いほど、読み手は複雑に感じ、ミスが多発する ステップが多いほど、手順書の保守が大変になる 長文説明を避ける 説明が長すぎると感じたら、コンセプトガイド等に分割すること チュートリアル 手順書に分類されるドキュメント 読み手に、特定のゴールを達成する方法（≒手順）を伝える（≒学習させる）ことを目的とする 長く、時間のかかるチュートリアルを、ユーザーがやり遂げる可能性は低い 長すぎる手順は、サービスが複雑すぎる可能性を示唆する ハウツーガイド 手順書に分類されるドキュメント 現実のビジネス課題を解決するための、特定の手順を説明する チュートリアルのような学習目的ではなく、実装に基づく課題解決が目的 以下、良いハウツーガイドの特徴 シンプルな言葉を使用する 行動を明確にする ハイツーガイドが解決する問題を継続的に改善する ガイドの冒頭には、前提条件を入れると良い リファレンスガイド 行動とその結果を説明する APIリファレンス、用語集、トラブルシューティングドキュメントなどが該当する トラブルシューティングドキュメント リファレンスガイドに分類されるドキュメント 既知の問題に対して、その回避策、または解決策を説明する 説明よりも、回避策に集中すること 読み手の大部分は、「なぜ問題が発生したか」ではなく、「どうやったら問題を回避、または解決できるか」に関心を持つため エラーメッセージとその説明、および解決策を列挙するのも手 テンプレート 変更に関するドキュメント リファレンスガイドに分類されるドキュメント 変更時期、顧客に影響が出たタイミングなどを整理し、トラブルシューティングに役立てる 以下の情報を記録する 過去のサポートバージョン、統合、または廃止予定の機能 パラメータや重要なフィールドの名前の変更 オブジェクトやリソースの移動 リリースノート リファレンスガイドに分類されるドキュメント（特に、変更に関するドキュメントの一種） 変更履歴の背景情報を記載し、読み手に対して、ある変更が生じた理由を説明する リリースノートには、以下の内容を記載する 新機能 バグ修正 既知のバグや制約 移行方法 テンプレート

やったこと 書籍「実践NextJS」1章 読了 学んだこと Route 系の用語整理 Tree/Subtree Tree ... 階層構造 Subtree ... 入れ子のTree Root ... TreeまたはSubtreeにおける根っこのノード Leaf ... 子を持たないノード Segment / Path example.com/profile/settings example.com ... ドメイン名 profile , settings ... Segment profile/settings ... Path 特定のPathに対応する Segment を、 「Root Segment」 と呼ぶ。 末端（≒子Segment を持たない）Segment を Leaf Segment と呼ぶ。 Dynamic Route / Dynamic Segment Pathが動的に変わり得るRouteを Dynamic Route と呼ぶ。 ID情報を含む場合など Dynamic Route を構成するSegment を Dynamic Segment と呼ぶ。 Route Segment の構成 app ディレクトリを頂点に、ファイル配置でRouteを表現する。 src/app/ ├── company-info │ └── page.tsx // localhost:3000/company-info ... └── page.tsx // localhost:3000/ (ルート) layout.tsx Header , Footer , サイドナビなど、全画面共通で表示したいUIを実装する場所。 また、layoutファイルはネスト出来る。 つまり、layoutファイルは、Segment毎に設けることが出来る。 Segment は Pageファイル必須ではなく、layoutファイルだけでも良い。 ナビゲーションの概念と用語 ハードナビゲーション ... 画面を再読み込みする画面遷移 ソフトナビゲーション ... 画面を再読み込みしない画面遷移 ※ナビゲーション ... 画面遷移のこと NextJS の SPAは「ソフトナビゲーション」。 加えて、データやレンダリングした画面をキャッシュしてくれる。 Dynamic Segment [categoryName] 部分が Dynamic Segment。 ディレクトリ構成 ├── categories │ └── [categoryName] │ └── page.tsx index.tsx ... <li> <Link href="/categories/flower">花</Link> </li> <li> <Link href="/categories/animal">動物</Link> </li> ... 所感 NextJS で言う Route は、ファイルシステムに近そう "Root Segment" の解説から、どのSegment も、必ずRootを持つ...ということになりそう layout ファイルを使いこなすことで、コードを共通化 が捗りそう dynamic segment は、機能としては理解できたが、有効なユースケースが思い浮かばない 経験を積めばわかるかな？

やったこと Design It! 14章 ~ 17章 読了 学んだこと 問題解決の際に役立つアクティビティ 10個 潜在的な解決策を探る際に役立つアクティビティ 9個 設計をうまく可視化する際に使用できるアクティビティ 10個 選択した設計を評価するアクティビティ 9個

やったこと Udemy SAP on AWS 練習問題 100問解いた 学んだこと メモ SAP oracle ワークロードは、SUSE Linux ではサポートされていない SAP HANA をAWS上で動かす場合、推奨OSはRHELかSUSE<br>SAPアプリケーションの場合、OSは色々(RHEL,SUSE,Oracle Linux, WIndows Server あたりがメジャー) システム移行 : AnyDB => HANA HANA DB をバックアップから復元する際は、 テナントDBのみ必要。SYSTEMDBは不要。 移行には、 "移行キー" なるデータが必要。 SAP Support Portal からダウンロードできる模様。 AWS Application Migration Service (MGN) <br>- ブロックレベルのレプリケーションを提供<br>- 基盤となるOSとDBを変更しないまま移行する、リフトアンドシフト向け AWS Data Provider for SAP : SAPアプリケーション関連のパフォーマンスメトリクスを収集できる ABAP プラットフォーム 1809 以降 => SAP カーネル version 7.73 以降 Oracle DB サポート状況は ... OS : Oracle Linux , Oracle 11g R2以降がサポート Launch Wizard にて、以下の流れでカスタムスクリプトを実行可能<br>- S3にカスタムスクリプトをアップロード<br>- Launch Wizard 所定の画面にて、スクリプトのS3 URLを指定<br>または、Launch Wizardから直接スクリプトをアップロードできる。 SAP カーネル version 7.45以降では、 IMDSv2をサポートしている。未満では、v1のみサポート SAP HANA データベースへのオプション 「SAP HANA 動的階層化」<br>ホット層よりもウォーム層に最大 5 倍のデータを保存できるようになり、クエリや更新に使用できるオンライン データ ストレージが可能になる。 HANAの移行。OS は変えずに、 AnyDB => HANA SAP 拡張モニタリング : SAPOSCOL 拡張機能<br>SAP システム内に追加のパフォーマンス メトリックとモニタリング機能を提供。<br>Cloud Watch 詳細モニタリング、Data Provider for SAP と並んで、監視用メトリクス設定の最有力候補 Backint Agent は、SAP HANA version 1.0 SP12 をサポート HANA Backint Agent ... DBのネイティブソリューション。 RHELおよびSUSEでサポート。<br>AWS Backint Agent ... DBのネイティブソリューションではない 。AWSが提供する、SAP認定ツール。 u-*tb1.metal は、ホスト テナントを持つ専用ホストとしてのみ起動できるベアメタル サーバー。 <br>u-*xlarge バリアントは、デフォルト、専用、またはホスト テナントで起動できる。 ファイル システムの SAP インスタンス セキュア ストア (SSFS)<br>データボリューム、各種ログ、バックアップの暗号化、暗号化用ルートキーの保護を提供する、DBネイティブ機能。 SAP HANA コックピット にて、バックアップ保持ポリシーを変更できる。<br>古いバックアップを自動削除する場合に活用できる。 IBM Db2 高可用性災害復旧用のオーバーレイ IP アドレス ルーティングを有効にするには、データベース EC2 インスタンスのソース宛先チェックをオフにする必要がある。<br>オンのままだと、送信元宛先チェックにより、トラフィックがブロックされる。 Oracle DBの移行 & エージェントのインストール不可 => Oracle Data Guardを使用したOracleデータベースのレプリケーション SLIC_HW_VERSION Linux 環境変数 : ハードウェア キーの計算に同じネットワーク カードが常に使用されるようになり、ライセンス キーが無効になるのを防ぐことができる

やったこと Design It! 13章 チームのアーキテクト力を強める 読了 学んだこと ポイント 現在、アーキテクトに求められる役割、仕事 なぜ、チームのアーキテクト力を強める（高める）必要があるのか チームのアーキテクト力を強める（高める）ために何ができるか 学び 現在では、チームのアーキテクト力を強める（高める）ことが求められる チームを成長させ、価値を生むアーキテクチャを設計できるよう導くことが、アーキテクトに求められる チームのアーキテクト力を高めると、以下の効果がある チームに、「自分たちのシステム」という意識が芽生え、以下の効果が得られる 皆が設計の意図を理解でき、設計の一貫性を保ちやすくなる コミュニケーションが効率化される アーキテクチャを批評できる人間が増え、以下の効果が得られる 品質が向上する 設計判断が早くなる などなど チームのアーキテクト力を強める（高める）ために、アーキテクトは以下を実施できる チームに、「自分たちのシステム」という意識を持ってもらう 「自分たちのシステム」という共同所有意識を持ってもらう そのために、チームメンバに多くの学習と成長の機会を与える チームの成長度合いに応じて、適切に権限を委譲していく アーキテクチャを協働で設計する メモ 現代ではコンテナやクラウドの台頭により、様々な技術を手軽に利用できるようになった。 私たちは、これらの技術を使用して、強力なアーキテクチャを構築できる。 同時に、私たちは、様々な技術の中から、自分たちの問題を解決できるものを適切に選択できる必要がある。 現在、開発者とアーキテクトの違いは希薄になっている。 アーキテクトに求められ得る役割は、以下のように変化している。 従来 : トップダウン型のリーダー 現在 : 一緒に設計でき、チームの能力を向上させることができるリーダー そんな現在のアーキテクトは、コーチであり、メンターであり、技術の第一人者である。 アーキテクチャを理解しているメンバーが増えるほど、チームは難しい問題へ取り組むことが可能になる。 こうした理解は、システムを共に設計することによって生まれてくる。 この章では、チームを成長させ、力を与える方法に触れていく。 アーキテクチャ思考を促進する メンバー全員がアーキテクチャに関心をもち、アーキテクトであろうとするチームは、以下の恩恵が得られる。 ソフトウェア品質が向上 ソフトウェアを批評できる人間が多いほど品質が向上する、という意図 迅速な設計判断 共同所有意識が高くなる => 「自分たちのシステム」という意識が芽生える 「自分たちののシステム」という意識が芽生えた結果、誰もが設計の意図を理解でき、設計の一貫性を保ちやすくなる。 コミュニケーションが効率化され、開発のベロシティも向上する。 メリットは非常に大きい。 大まかな方針は、「チームの設計スキルを高めながら、同時にそれを使ってアーキテクチャを設計していく」こと。 これを実現するため、チームが順調に進む手引きを行い、学習と成長の機会を与える。 （設計判断を全部監視したりしない） 意思決定を促し、スキルの成長を促進する 共同所有意識を高めるには、チームに学習と成長の機会を与える。 普通のソフトウェアアーキテクト 優れたソフトウェアアーキテクト チームの手を借りることなく、一人でパターンと技術を選定する チームの意見に基づいて協働してパターンと技術を選択する 詳細なドキュメントを書く。ドキュメントを完璧に完成させ、一度だけリリースする チームでドキュメントを作成、レビュー、更新する。得た知見から、チーム用のテンプレートを構築する 全ての設計判断を下す チームに判断方法を教える。設計判断を行うために必要な情報をチームに提供する。レビューとフィードバックに努める 誰が特定の要素を構築するか決める チームが自己組織化し、自分でタスクを選択できるようになるよう手伝う アーキテクチャへの変更を避ける アーキテクチャを変更しやすくする 技術的な判断を下す 技術的な判断について合意形成を行う 優れたアーキテクトになるために何が必要なのか？ これを、チームが学んでいく必要がある。 学ぶために必要なことは、「練習」である。 安全に実践する機会を作り出す 設計判断を学ぶため、練習の機会を設ける。 練習には、以下のような手段がある。 ペア設計 経験あるメンバーとペアとなって設計作業を行い、学びを得る 足場を作る 学習促進及び強化を目的とした支援構造 設計作業をサポートするためのテンプレート作成 建設的な批評 スケルトンコード作成 良い例と悪い例を共有 アーキテクチャのガイドレールを導入する 設計の選択肢を制限し、目的範囲から逸脱しないことを助ける仕組み 設計ポリシー ... やるべきことや避けるべきことを説明した指示。シンプルだが強制は困難 コードに対する静的解析の導入 説明会（勉強会）を開く 設計権限を委譲する 大事なのは、重要な品質特性（つまりアーキテクチャ）を危険にさらすことなく、できるだけ多くの設計権限をチームに委譲すること。 「権限の7つのレベル」という考え方がある。 この考え方から、委譲すべき権限、そうでない権限を判断できる。 権限レベル 名前 概要 1 指示する アーキテクトが設計判断を下し、チームに指示する 2 説得する アーキテクトが設計判断を下し、その判断が正しい理由をチームに示す 3 相談する 設計判断を行う前にチームに意見を求める。設計判断はアーキテクトが行う 4 合意する チームと協働し、チームの判断として設計判断に合意する 5 助言する アーキテクトは助言や知見共有に留まり、設計判断はチームが行う 6 尋ねる チームが行った設計判断に対して、アーキテクトは、その判断が正しい理由をチームに尋ねる 7 委譲する アーキテクト以外のメンバーで設計判断を行う。チームが、判断に責任を持つ 状況に応じて、適切な設計権限を適切なレベルで委譲する。 「適切」を把握するには、試行錯誤が必要。 以下のような場合では、設計権限を維持する方向で検討すると良い。 失敗のリスクが高い場合 チームが未熟な場合 権限レベル1,2,3 ぐらいでよい 確信が持てない時、「適切な機会が現れるまで設計権限を維持する」という判断を下すのは悪くない。 反対に、以下のような場合設計権限を委譲する方向で検討すると良い。 チームが既に経験を積んでいる場合 チームがアーキテクチャについて学ぶようになり、チームを導け得る自信が得られてきたら、共同ワークショップを実践すると良い。 共同ワークショップの中で、権限レベル5,6,7辺りで振る舞うことが出来る。 （この時、アーキテクトはファシリテーターとしてチームをサポートすることになる） 意思決定プロセスに複数のステークホルダーを巻き込む例 アーキテクチャについての会話もするよう、チームに働きかける 協働ワークショップへの参加を働きかける デザインスタジオ、リスクストーミング、シナリオウォークスルーなど チームの影響力を確認し、発生していることを理解する アーキテクチャーブリーフィング、サニティチェックなど 良い例が存在する場合には、成果物の作成を委譲する 共にアーキテクチャを設計する 顧客に価値を届けるのはアーキテクチャであり、アーキテクトではない。 チームが価値を生むアーキテクチャを設計できるよう導くことが、アーキテクトの仕事である。 アーキテクトの重要な責任を次のように見直す。 エンジニアリングの観点から問題を定義する アーキテクトには、アーキテクト上重要な要求、特に品質特性を鄭ぐする責任がある。 ステークホルダーの真のニーズを見誤らないよう、人間中心の設計手法を駆使して要求を収集する。 システムを分割し、要素とチームに責任を割り当てる チームを導き、望ましい品質特性を促進するパターンを見つけ出す。 重要な品質特性が確実に達成されるよう、最小限のアーキテクチャを設計し、その他のすべての判断を後続の設計者に委ねる。 全体に目を向け、設計の一貫性を保ち続ける 設計が現れてくるタイミングでは、それをしっかり把握する。 アーキテクチャを実装するタイミングではチームを手助けする。 チームやステークホルダーに適した最も軽量な文書化を行い、設計判断を正確なモデルとして記録する。 記録したモデルから、システムを見通したり、判断を評価したり、リスクを明らかにしたりする。 品質特性間のトレードオフを決定する 設計判断を重ね、アーキテクチャが進化する中で、チームがトレードオフを調整するのを助ける。 リスクを使い、どれくらい設計するかや、何に専念するかを決定する。 技術的負債を管理する やむを得ず負った技術的負債を認識し、返済の戦略を立てる。 技術的負債を、「成功のために避けられない結果」と捉え、負債を負うことと返済をうまく計画に組み込み、戦略的に管理するよう努める。 チームのアーキテクチャスキルを高める チームに、「自分たちのシステム」という意識を持ってもらえるよう、働きかける。 チームのためにアーキテクチャを設計するのではなく、チームと共にアーキテクチャを設計する。

やったこと Design It! 12章 アーキテクチャに通知表をつける 読了 学んだこと ポイント アーキテクチャ評価とは 良いアーキテクチャ評価の特徴 評価ワークショップの目的 学び アーキテクチャ評価とは、アーキテクチャがどの程度目的を達成しているのか知るプロセス 良いアーキテクチャ評価 頻繁に評価を行い、フィードバックサイクルを回す 評価の観点 アーキテクチャはどの程度良いか？ アーキテクチャはどのように良いか？ 評価と価値のバランスを取る イメージは、テストピラミッド たくさんの軽い評価と、少数の重い評価でバランスを取る 様々な課題を探る いくつかある観点から、アーキテクチャにおける課題を探り、既知の未知をふやす 同じ観点の問題ばかり探るのは、よくある失敗 評価ワークショップを開き、評価に必要なデータを収集して分析し、改善に役立てる メモ アーキテクチャを評価・改善することによって、後続のプログラミングは、更に効率的なものになる。 評価から得たフィードバックは、学び、設計判断への肯定的な意思の作成、リスク軽減、アーキテクチャの改善など、様々なことに活用できるはずだ。 評価し、そこから学ぶ アーキテクチャの評価は、アーキテクチャが目的を満たしている程度について学ぶプロセス。 アーキテクチャの評価は何回か行うことになる。 少なくとも、「最後に一度だけ実施すればよい」という考えは間違っている アーキテクチャ全体を一度に評価するのは非常に困難 アーキテクチャが誤っていれば、振出しに戻る 評価で得るべき学びの観点は、以下の二つ。 アーキテクチャはどの程度良いか？ アーキテクチャはどのように良いか？ アーキテクチャが、「アーキテクチャ上重要な要求」を十分に満たしているほど、アーキテクチャは目的を満たしているといえる。 設計をテストする アーキテクチャを 早くにテストし、早く失敗し、早くフィードバックを得よう。 このサイクルを素早く回そう。 アーキテクチャの評価に必要なものは、以下の3つ。 視認できる成果物 ステークホルダーの視点から見た「よりよい」または「悪い」を定義したルーブリック レビュー計画 ◆ルーブリック 学習の達成度を示す評価基準を、観点と尺度からなる表として示したもの 評価できるものを作る 実物が無ければ、評価は非常に難しい。 ホワイトボード上のスケッチでも、アーキテクチャ記述でも構わないので、視認できる成果物を作成する。 欲しいフィードバックに合わせて、評価の準備を行う。 例）特定の品質特性の評価が欲しいなら、品質特性に関連するレビューの準備を行う ... など デザインルーブリックを定義する デザインルーブリックとは、アーキテクチャの適合性を判断する時にレビュアーが採用する基準を定義するもの。 ルーブリックは、「観点」と「尺度」から成る。 観点に品質特性シナリオを例としたルーブリックを示す。 品質特性 シナリオ（観点） 評価 (1-4) 可用性 インデックスが利用できない場合でも応答する 可用性 メンテナンス中を除いて、結果は常に返される パフォーマンス 結果は平均負荷で5秒以内に表示される スケーラビリティ このシステムは、今後7年間で年間5%のデータ増加を処理するように拡張できる 評価尺度 ... 観点の評価方法を定義 1 : 期待に応えられない、または評価できない ... 4 : シナリオを満足させる ルーブリックを作成する際のポイントを示す。 観点は、アーキテクチャ上重要な要求に基づいて選択する 以下を満たす、優れたルーブリックとなり得る 重要かつ不可欠 観点が重複しない 観察可能かつ測定可能 明確 観点の評価尺度を決定する 上記例では 1 ... 4 の4段階だが、2段階など、必要に応じて変更できる 5段階以上は、使用を控えること 評価者によって尺度のブレが生じ始めるため レビュアーが評価した際、「何を考えてその評価を下したのか」という情報は非常に貴重。 これを得るために、インサイトを生成する。 インサイトを生成する インサイトとは、「設計がアーキテクチャ上重要な要求を満たしているか」をレビュアーが意見するために使用するもの。 インサイトは、アンケートや探求、リスクの導出やコードの分析など、様々な方法で生成できる レビュアーがインサイトを文字や言葉にするのを助け、評価を下した理由を明確化する。 ルーブリックで答えなくてはならない情報は何か？を把握すると、どういったインサイトが効果的か見えてくる。 ルーブリックの観点 観点を評価するのに役立つインサイト リスクの量 リスクストーミングなどでリスクを明らかにする 不確実性の量 質問-意見-懸念のワークショップを開き、未解決の質問を生成する レビュアーの合意 投票、アンケート、サムズアップ評価など デザインの一貫性 設計状態を一覧化する 問題への適合度合い 不安定な部分、問題点、リスク、質問を見つけ出す。 技術的負債 現在実装できない、付加価値あるユースケースを一覧化する 品質 品質の高低の閾値を定義する 評価ワークショップを開く アーキテクチャ評価ワークショップの目標は、アーキテクチャを評価するのに必要なデータを集めて分析する事。 望ましい品質特性やその他アーキテクチャ上重要な要求をどれだけ満たしているか確認する。 大体、以下の流れ。 準備する ルーブリックの定義、レビュアーの招待、評価で使用する成果物の検索または作成など レビュアーには、アーキテクチャで使用する技術に明るい人物が良い レビュアーに前もって伝える -　評価の目的、システムのコンテキスト、成果物、ルーブリックなど、評価に必要な背景情報を前もって伝える 評価する 分析する リスクと未解決の問題を探し、アーキテクチャがどのように良いか判断する 事後点検する ワークショップで得た学びから、次のアクションアイテムを決定する 見解の要約とアクションアイテムを、すべての参加者に共有する 早くから評価をはじめ、頻繁に継続的に評価する 早い段階で評価するほど、早く改善できる。 可能であれば、アーキテクチャ評価を開発ルーチンに組み込もう。 評価ピラミッドを使ってコストと価値のバランスを取る 評価ピラミッドのイメージは、テストピラミッド。 大部分は、低コストで素早くチェックできる評価 個別の設計判断 少数の、徹底的で高コストな評価 システム全体と、いくつかのアーキテクチャ上重要な要求の相互作用 上記二つの評価の間に一貫性を持たせる、対象を絞った評価 一つの判断、コンポーネント、アーキテクチャ上重要な要求 様々な課題を探る アーキテクチャにおける課題を探る観点を示す。 リスク 発生する可能性があるものの、まだ発生していない良くないこと 未知のこと 未解決の問題から得られる、わかっていないこと 既知の未知と、未知の未知は全然違う 問題 顕在化してしまった、良くないこと 理解のずれ ステークホルダーの考えと設計のずれ 進化するアーキテクチャに対して、理解が遅れている など アーキテクチャの浸食 設計されたアーキテクチャと実装されたアーキテクチャの差 状況の横滑り 新事実の発覚や状況の変化によって、ビジネスの推進要員や判断を左右するコンテキストが変化すること 常に同じ種類の問題を探そうとしてはならない。 様々な課題を探ることで、既知の未知を増やすことが出来る。

やったこと Design It! 10章 設計判断を可視化する 読了 学んだこと ポイント 図を描く際の注意点 良い図を描くためのポイント 学び ビューを描く際の注意点 関心事一つにつき、一つのビュー 図での表現が難しい部分は、注釈・表・説明文で補足する 品質特性、優先度の高いリスクを説明するために、拡大ビューを描く アーキテクチャが品質特性を保証する方法を示す 良いビューを描くためのポイント 図に凡例を書く 選択したアーキテクチャパターンに合わせて、図を構成する 図の一貫性と、単純さを目指す 叙述的散文を挿入し、アーキテクチャの補助的説明としてストーリーを表現する 所感 「単一責任の原則」というが、これは作図にも当てはまることになるみたい。 「シンプルにする」の一つの具体例が、「焦点を一つに絞る」になりそう。 メモ アイデアを共有する最良の方法は、アイデアを可視化する事。 可視化することで、認識を素早く共有でき、議論も可能。 共有するだけなら、アナログツールにて作成したスケッチで十分。 綺麗に作図する必要はない。 図を使い、設計判断によって品質特性が向上するストーリーを伝える。 ストーリーと図がかみ合うと、アーキテクチャの理解促進につながる。 異なる視点からアーキテクチャを示す アーキテクチャの詳細を一つの図で描くことはほぼ不可能。 たとえ描くことが出来たとしても、誰も理解できないような非常に複雑な図になる。 一つにまとめるのではなく、一つの関心事に絞った図を、表現したい関心事の数だけ作成する。 一つの関心事に絞った、アーキテクチャに関するストーリーを、ここでは ビュー と呼ぶ。 要素責務ビューで要素が何をするのかを把握する 箱で要素が何をするのか、線で箱をつなぎ、要素間の関係を表現する。 図での表現が難しい共有すべき必須情報は、注釈・表・説明文などを使用して埋め込む。 絞込ビューで拡大または縮小する 図に、より詳細な情報を詰め込むこともできる（≒解像度を上げる）。 三層アーキテクチャの解像度を上げる例。 ![[Drawing 2024-01-13 16.36.46.excalidraw]] より詳しいパッケージ関係を図示したことで、保守性について詳しく知ることが出来る。 モデルレイヤーとユーティリティレイヤーは、全コンポーネントから参照される。 全部描くと図が煩雑になるため、あえて記載していない。 解像度を上げると、図が煩雑になる可能性がある。 図で表現したいことを一つに絞り、特化させることを意識すると、ある程度マシになる。 以下を共有する際、詳細化は非常に有効。 特定の品質特定を説明する 優先度の高いリスクを減らす アーキテクチャが品質特性をどう促進するか示す 品質特性の実現方法を示したビューを、品質特性ビューと呼ぶ。 品質特性と関係ある情報のみ記載することで、品質特性に焦点を当てることを目的とする。 例）可用性を満たすために、冗長化できるアーキテクチャを選択し、図示する 図だけで品質特性の説明が困難な場合は、説明文や表で補足する。 ビュー間の要素を結びつける 分割した複数のビューの関連を示したい場合、ビューの関連を明示した情報（マッピングビュー）を作成する。 コンポーネント 割り当てられたチーム 備考 Web UI A チームはフロントエンドWeb開発の専門家で構成 表示ビジネス A このコンポーネントは、Web UI と密接に関係している 検索サービス B 検索インデックス B ... ... ... ビューの関連を示すことが出来れば、形式に拘る必要はない。 表で十分な場合も多い。 ラフスケッチでアイデアを感じる アイデアを共有する目的であれば、図の精密さは重要ではない。 むしろ、素早い反復と形式ばらないコミュニケーションを前提とするなら、精密な図を描く時間や修正する時間が無駄になりかねない。 アイデアを広げて試行錯誤している際は、単純な図で構わない。 精密な図を描くのは、アイデアが固まり、設計判断が収束してきたらでも遅くはない。 カスタムビューを作成し、必要なものを正確に示す ユースケースをうまく説明できる図は、図の作成ルールから外れた図であっても、価値がある。 この場合、特定の目的に合わせた、カスタムビューを作成する。 素晴らしい図を描く 素晴らしい図とは、アーキテクチャの概念や土台を正確に反映した図。 素晴らしい図を描く際のポイント。 すべきこと 避けるべきこと 図に関連するメタモデルの各部分を要約した判例を作成する 読者が表記法を知っていると仮定すること（UMLでも） 説明的なタイトルを追加して、図にどのような種類の構造があるかを伝える 全ての要素を一つの図に含める 精密さを高めるためにテキスト注釈を追加する 白黒で印刷すると意味が失われる表記を使う 全ての図にわたって一貫した表記法を使用する 余計な飾り、多種多様な形や線を使い過ぎる パターンをわかりやすくする 説明文を省略する 凡例を上手に使う 図内で何が起こっているかを表現するためにも、凡例は必須。 凡例が無ければ、何が起こっているのかを理解するのは困難。 例え一般に普及している表記（UMLなど）でも、凡例を載せる。 すべての読み手が、一般的な表記を理解しているわけではない パターンを際立たせる 選択したアーキテクチャに合わせて図を描くことで、アーキテクチャを直感的に理解できる。 例）レイヤー構造であれば、層に合わせて要素を並べ、どの層に属するか記述する。 ![[Drawing 2024-01-13 16.36.46.excalidraw]] 以下のような戦略が考えられる。 パターンを反映した名前を選択する 強調表示する パターンを反映するよう、要素の配置を工夫する 語彙を統一する 一貫性と単純さを目指す 伝えたい焦点を絞るよう、余分な詳細を避ける。 詳しすぎる詳細は、読み手の注意があちこちに分散し、本当に伝えたいことがぼやける 伝えたいことに応じて、要素の色や形を統一し、読み手の理解を促進する。 色や形を選ぶのは、異なるアイデアを際立たせるためであり、綺麗に見せるためではない 読み手は、色や形からも意図を見出そうとする。要素の色や形の不統一は、意図しない誤解を与えかねない 叙述的散文を提供する アーキテクチャについてのストーリーをビジュアル的に補助する手段として、叙述的散文を使用する。 ◆叙述的散文 物事を客観的な説明によって順に並べた文章のこと 叙述的散文によって、アーキテクチャのストーリーを語る。 アーキテクチャはどこから来たのか どう動くか どこに向かっているのか など 表やテキストの段落、箇条書きなどに用いる。

やったこと Design It! 11章 アーキテクチャを記述する 読了 学んだこと ポイント アーキテクチャ記述の種類 優れたアーキテクチャ記述を作成するためにできること 設計根拠を残す効果 学び アーキテクチャ記述には、いくつか種類がある 部族的な方法 共通の方法 形式的な方法 無駄な方法 優れたアーキテクチャ記述を作成するためには、以下が重要 聴衆のことを考えて作成する ステークホルダーの関心事に合わせて、ビューを構成する 設計根拠を残す 設計根拠を残すことで、読み手に設計判断の意図を伝えることが出来る 読み手には、アーキテクチャや設計判断の判断残量として機能する これにより、アーキテクチャや設計の一貫性を保ちやすくなる 所感 「アーキテクチャ記述にスライドを使用するな」という話について あえて機能の制限されたツールを使用することは、表現したい本質から意識がそれることを防ぐ効果があることを理解した。 スライド作成ツールを使用すると、きれいな作図に意識を取られる可能性が生まれる メモ 優れたアーキテクチャ記述は、チームに明確なビジョンを与える。 設計判断をすべてのステークホルダーに届け、品質向上に寄与する。 この章では、素晴らしいアーキテクチャ記述を作成する方法を学ぶ。 全体像を語る アーキテクチャとコードの間には、常に何らかのずれがある。 コードでは、全アーキテクチャ上の設計判断を表現することはできない。 特に、計画的な設計が必要なプロジェクト初期では、コードもないため、アーキテクチャを評価できない。 このようなときに、アーキテクチャ記述は重宝する。 アーキテクチャ記述は、以下の効果がある。 整理する 技術同士、または技術と人々がどう連携するのか整理し、記述する 技術サイドとビジネスサイドの間で使用できる、共通の語彙を確立する 品質特性にスポットライトを当てる 考えを明確にする 記述する過程で、頭の中の考えを整理できる わかっていること、わかったつもりになっていること、わからないことを明確にできる 評価できるものを作る 見せびらかす 優れたアーキテクチャ記述は、顧客や管理職を安心させる チームメンバーに対しても、リーダーシップを発揮する 状況に応じた記述方法を選ぶ アーキテクチャ記述には、複数の記述方法が存在する。 費用対効果を高めるためには、現在のプロジェクトとチームの状況に応じて、適切な記述方法を選択する必要がある。 記述方法 概説 適した状況 例 部族的な方法 チーム内での認識合わせに重きを置いた、チーム内でのみ通用するような記述。<br>変更は容易だが、チーム外に対して共有するのは困難。 アーキテクチャが固まっていない、プロジェクト初期など ラフスケッチ、ストーリーテリングなど 共通の方法 チーム外の人々にも共有できる、共通の記述。<br>変更容易な状態を保ちつつ、部族的な方法よりも共有容易な運用が求められる。 アーキテクチャが成熟し、変更する頻度が低下してきた段階 アーキテクチャ俳句、コーディングスタイル<br>アーキテクチャデシジョンレコードなど 形式的な方法 リスクの高いシステムや、高度な調整を必要とするプロジェクトで必要となる、<br>より高い精度や精密さを必要とする記述。<br>膨大な量になる傾向があり、多くの時間と労力を要する。 リスクの高いシステムや、高度な調整を必要とするプロジェクト SAD(Software Architecture Description) 無駄な方法 変更困難で共有も難しい記述方法。<br>本質以外のことに意識がそれる可能性も 無し スライドで作成するアーキテクチャ記述 SAD（Software Architecture Descriptionには、様々なテンプレートが存在する。 有名なSADたちは、いずれも以下の基本部分を含む。 導入と事前情報 SADの概要と照会 ステークホルダー、ビジネス目標、アーキテクチャ上重要な要求の概要 コンテキストビュー 関連ビュー 一つのビューでは、伝えたいこと全てを書ききることは不可能 品質特性やそれ以外の要求を満たす方法について、関連するビューを作成して説明する リスク、未解決の質問、今後の課題 付録 優れたアーキテクチャ記述を作成する 優れたアーキテクチャ記述は、以下4つの特徴を持つ。 聴衆を念頭に置いて特別に作られている アーキテクチャの複数のビューを示している 要素とその責務を明確に定義している 設計判断についての根拠を説明している 言い換えると、これら4つの特徴を意識することで、優れたアーキテクチャ記述を作成できる。 これらを守ることは、後述する「時間を無駄にするのを避ける」ことにもつながる。 時間を無駄にするのを避ける 変更困難で共有も難しいアーキテクチャ記述も存在する。 その最たる例が、「スライドによるアーキテクチャ記述」である。 共有が難しい : 誰かがプレゼンしなければ、スライドは意味を成さない 変更が困難 : 整えた見栄えを変更するのをためらってしまう 聴衆に配慮する 聴衆のことを理解できれば、彼らが必要としているアーキテクチャ記述を作成できる。 聴衆が価値を置くものを考える。 どのような情報を処理するのを好むか 渡した情報をどう使うか など 理解しやすさに専念する 大事なのは、聴衆とのコミュニケーション。 聴衆にとってなじみ深いドメインの言葉を使用、アーキテクチャ記述を作成すると良い 平易な話し方を心掛け、専門用語を避ける 背景知識が必要なことを示すために、アーキテクチャの概念を簡単に定義する など 以下、アーキテクチャ記述で気を付けるべきこと。 すべきこと 避けるべきこと 新しいアーキテクチャあゐ年は、初出のタイミングで定義する 不必要に新しい概念を導入する ドメイン領域の言語を話す 全員が図の表記法を理解していえると思い込む 図に凡例を含める 専門用語を使う 共通のテンプレートが存在する場合はそれを使用する ステークホルダーの関心事を中心にビューを構成する ステークホルダーに合わせて、アーキテクチャやそれに伴う様々な設計ドキュメントのビューを構成する。 開発者は、コードの構成、デプロイ、コンポーネントの相互作用などを知りたがる テスターは、I/Fや通信プロトコルを知りたがる プロダクトオーナーは、技術的な依存関係や全体の進捗を知りたがる など そのためには、「ステークホルダーが何を知りたがるか？」を考える必要がある。 また、アーキテクチャ記述には、少なくとも以下を加えるべき。 設計判断とその根拠 設計したものの構造 アーキテクチャの文書化方法を決定する際は、必ず聴衆を考慮する。 ビューポイントを確立する 「ステークホルダーの特定の関心事に関連するまとまり」に従って、アーキテクチャを説明する方法を定義するもの。 どんなビューか、誰向けのビューか、ビューの表記法や語彙、規則を定義する。 例えば、コンポーネントの配置先を知りたいステークホルダー向けには、以下のようなビューになる。 コンポーネント デプロイ先 Web UI ユーザーのブラウザで実行される ... ... カスタムビューポイントを作成する ステークホルダーの特定のニーズを満たすために、カスタムしたビューポイントを構成できる。 特に、品質特定を中心としたビューポイントを構成することは多い。 スケーラビリティ、セキュリティ、保守性のビューポイント アーキテクチャが特定の品質特性シナリオをどのように満たすか示す 規制のビューポイント 規制要求に関心を持つ特定のステークホルダーグループに監査を実施するために必要な情報を提供する 学習容易性のビューポイント あるいは チーム受け入れのビューポイント 新しいチームメンバーが、スムーズに開発へ参加できることを目標とした、開発プラクティスを確認できるようにする ビジネスインパクトのビューポイント アーキテクチャの各部分がビジネス価値にどのように貢献しているか示す ビューポイントは、伝統的なアーキテクチャ記述では必須。 部族や共通のアプローチでも、効果はある。 ビューは、アーキテクチャを効果的に共有できるようアイデアを構成するのに役立つ。 判断の論理的根拠を説明する 設計根拠とは、各設計を決定した理由を説明するもの。 品質特性のトレードオフ、コスト、チームメンバーの能力や外的要因など、様々な要因をもとに設計判断を行うはず。 その判断を行った背景を記載すること。 設計根拠を残すことで、読み手は設計の意図を理解できる。 理解した意図から、アーキテクチャの一貫性に寄与する可能性が高まる。 選ばなかった道を説明する 様々な候補の内、選択されなかった設計判断とその理由を残す。 背景知識は、読み手がアーキテクチャやコードを正確に理解することを助ける。

やったこと Design It! 9章 アーキテクチャデザインスタジオを開く 読了 学んだこと ポイント アーキテクチャデザインスタジオの目的 短めのタイムボックスを設ける目的 ワークショップの流れ デザインアクティビティ 学び アーキテクチャデザインスタジオの目的は、グループができるだけ色々なアイデアをできるだけ早く作成すること そのために、短めのタイムボックスを設ける 時間をかけるだけ優れたアイデアがでる ... とは限らない 短めのタイムボックスを設定し、短時間で、効果的なデザイン探求を目指す ワークショップの流れは以下の通り 作成 => 共有 => 批評 を繰り返す 結果をまとめ、次のアクションを決定する 結果と次のアクションを記録する デザインワークショップ内での活動（デザインアクティビティ）は、いくつか選択肢がある 目的に応じて、デザインアクティビティを選択する メモ デザインに時間をかけ続けても、必ずしもより良いデザインとなるとは限らない。 デザインにかける時間に制約を設けてることで、無駄を省くことが出来る。 この教えは、「デザインスタジオ」として普及した。 アーキテクチャ デザインスタジオを計画する デザインスタジオでは、グループができるだけ色々なアイデアをできるだけ早く作成することを目的とする。 そのために、探求に費やす時間を大きく制限する。 上記目的を達成するために、デザイン探求では、早く（Fast）、効果的で（effective）、楽しいもの（fun）にする（これをデザイン探求の「３つのF」と呼ぶ）ことに重きを置く。 デザインスタジオでは、3種類のアイデアが生まれる。 作るもののアイデア 有望なアイデア モデルやプロトタイプを作成して、詳細を具体化していく もっと探求が必要なアイデア 「前提が間違っている」「重要な情報が欠けている」などを発見する 新しい疑問としてのアイデア アイデア探求の過程で、解決したい問題の新しい問題に気付くことがある（問題を、事前に発見できたことになる） ステークホルダーに報告し、問題に対する理解を深めることが出来る ワークショップ以前 : 準備 ワークショップの目標を定め、招待する人を決定する。 目標は、1,2つ程度定める。 目標を明確に定めるには、以下について理解を深める必要があり、そこそこ大変。 - ビジネス目標 - 品質特性 - アーキテクチャ上重要な要求 - など キックオフ 以下を行う。 解決したい問題とアーキテクチャに関する情報を参加者に共有し、参加者の認識を一致させる。 デザインスタジオの目標を共有する 作成 - 共有 - 批評 のサイクルを繰り返す アイデアを探求し、可能性についてグループの理解を深める ◆作成 一人、または少数のグループでワークしょんぷのゴールに向かって取り組む。 アイデアのスケッチ、モデル化など。 アナログツールを使用すると良い。 必ずタイムボックスを設け、その時間内で完結させる。 ◆共有 各グループが作成したアイデアを共有し、自分たちの設計が目標をどのように満たすかを説明する。 完全な説明を避け、要点の説明に留める。 タイムボックスが、完全な説明を避ける仕組みとして機能する 共有する段階では、聴くことを意識し、質問は避ける（質問は、次の批評で行う）。 ◆批評 他のグループのアイデアを批評する。 目標に関する設計のメリットに評点を当てる。 言い換えると、否定的で非建設的な批評は避ける。 ◆繰り返す 作成-共有-批評 により、素早い思考の発散と収束を促進する。 これを繰り返し、学びを積み重ね、よりよいアイデアの議論につなげる。 また、繰り返しの中で、メンバーに合わせてルールを調整すると良い。 デザインスタジオを閉じて、次にやることを決定する ワークショップの結果をまとめる。 まとめ結果から、次のアクションを決定する。 最も注目すべきアイデアは何か？ 対処すべき重大なリスクは網羅できたか？ 実験すべきことはあるか？ など まとめや次のアクションは、記録に残そう。 適切なデザインアクティビティを選択する デザインスタジオの進め方には、いくつかのアクティビティがある。 ワークショップの際には、目的に応じてアクティビティを選択し、カスタマイズできる。 適切な参加者を招く ワークショップの質は、参加者に左右される。 また、参加者が多すぎると、ワークショップの結果がコストに見合わない可能性が高い。 適切な大きさのワークショップ 大規模なグループは、以下の問題がある。 管理が難しい コミュニケーションに時間がかかる スケジュールの調整が難しい 大規模なグループのままだとワークショップはうまく機能しない。 そのため、いくつかの小さなグループに分割するとよい。 多様な聴衆を招待する 活発な議論を呼ぶために、以下のようなメンバーを参加者に加えると良い。 異なる価値観を持つ参加者 異議を唱えることができる参加者 まずは、重要なステークホルダーを招く。 後は、価値観が偏らないように、参加者を調整する。 グループの力を賢く利用する グループワークでは、 "集団思考" に陥らないよう注意する必要がある。 周囲に同調しているだけの、静かな大多数を探し、コミュニケーションを促そう。 意見の不一致がない状態は、衝突を恐れ、集団思考に陥っている可能性を示す。

やったこと Design It! 8章 意味のあるモデルで複雑さを扱う 読了 学んだこと ポイント アーキテクチャモデルを構築するメリット アーキテクチャのメタモデルを作成する目的 アーキテクチャモデルをコードに盛り込むための手段 学び アーキテクチャモデルを構築 & 更新し、アーキテクチャの理解を促進する アーキテクチャのメタモデルを記述し、アーキテクチャモデルの理解を促進する 新しい概念をブラッシュアップし概念を固めていく 概念の更新に合わせて、メタモデルに矛盾が生まれないよう規則を更新する 良い名前を使う アーキテクチャモデルをコードに盛り込むために、以下のような手段がある コードの命名に、アーキテクチャモデルの語彙を使用する 品質特性を損なうようなコーディングが出来ないようにする ツールで強制できる状態がベスト 時点で規律や戒めに頼る コメントにて、設計根拠を説明する 所感 アーキテクチャの一面を説明するモデルとして、アーキテクチャモデルは役に立つ。 概念、規則、メタモデルなど、モデルをうまく説明するための定義がいくつか登場。 全体的に抽象的な話が多く、理解が難しかった。 うっすらイメージできるレベルで、人に説明できるレベルまで理解できているとは言えない。 何か一つ、説明できるような例を経験したり思いついたりすると全然違うと思う。 メモ ソフトウェアは、多かれ少なかれ複雑さを抱える。 解く問題が難しいほど、後から機能を足すほど、ソフトウェアは複雑になっていく。 複雑さを抑えるために何ができるか見ていく。 アーキテクチャを見通す アーキテクチャをうまく説明できる、新しい抽象概念を作成する。 新しい抽象概念は、図と同じように、アーキテクチャのある一面を説明する。 優れた抽象概念は、アーキテクチャを正確かつ精密に説明できる「アーキテクチャモデル」となる。 優れたアーキテクチャモデルの利点を示す。 設計の語彙を確立する アーキテクチャモデルを指す言葉で会話ができる 関心を持つべき細部に注意を向ける 品質特性やその他のシステム特性を見通せる アーキテクトの意図を記録できる なぜモデルに書いた方法を選択したのか、モデルの背後にある意図を表現できる 全てのモデルには、「概念」と「規則」がある。 メタモデルを記述する アーキテクチャのメタモデルは、モデルの「概念」と「規則」を定義する。 ![[Drawing 2024-01-09 20.17.26.excalidraw]] 概念は、アーキテクチャにおける要素や関係になる。 概念を定義したら、その概念を使用するための規則を設定する。 新しい概念を固定化する 新しいアイデアから、概念を定義する。 アイデアのブラッシュアップに合わせて、概念も更新していく。 アイデアが固まってくれば、概念が固まってくる。 十分に固まった概念は、概念を指す言葉で意思疎通が可能になる。 矛盾を調整する 新しい概念を追加したり、パターンをマージすると、規則に矛盾が生まれることがある。 矛盾は、アーキテクチャの一貫性を損ない、メタモデルを見た人に誤解を与える。 そのため、生まれた矛盾はうまく調整する必要がある。 つまり、新しい概念を追加したり、パターンをマージする場合、矛盾が生まれないよう規則の更新も必要となる。 また、規則には、アーキテクチャに課すと決定した「概念上の制約」も記述する。 これにより、特定の品質特性を促進できる。 （概念上の制約を維持している限りは、特定の品質特性を維持できる ... という考え方） 良い名前を使う 良いコードに良い名前が必須なのと同じように、良いアーキテクチャにも良い名前は必須。 アーキテクチャの場合、問題の理解が深まるほど、概念に付ける名前も変化する。 名付けには、7段階ある。 No ステージ 名前（例） 1 名無し 何かをするもの 2 無意味 クランベリー 3 的確 ジョブスタータープロセス 4 的確かつ完全 データフェッチャー、チェッカー、トランスフォーマー 5 適切な行い データ変換ジョブランナー 6 意図 データプリペアラー 7 ドメイン抽象 データ準備エージェント コード内にモデルを構築する モデルはアーキテクチャの見通しを良くする。 構築したモデルの名前をソースコードに持ち込むことで、アーキテクチャとソースコードが関連するようになり、理解の促進につながる。 他にも、以下のような利点がある。 概念的な設計の一貫性を維持し、望む品質特性の維持に貢献できる モデルとコードの足並みがそろい、理解が容易になる ドキュメントの必要性がいくらか軽減する アーキテクチャの語彙を適用する アーキテクチャでは、レイヤーやサービス、フィルターについて表現する。 コードでは、パッケージやクラス、メソッドを実装する。 アーキテクチャの抽象概念をコードに移行する際、用語を揃えないと、混乱の原因となりかねない。 用語を揃えるためには、コードに、アーキテクチャの語彙を使用すると良い。 例） レイヤーパターンを使用する場合は、コードパッケージをレイヤーと呼ぶ パイプとフィルターパターンを使用する場合は、クラス名に「パイプ」や「フィルター」を使用する システムメタファーとしてパイロットやナビゲーターといった単語を使っている場合、単語や型の名前に使用する 要素間の関係を強制する コードの構成は、コード内のアーキテクチャ構造に大きな影響を与える。 言語仕様（パッケージプライベート、アクセス修飾子など）を活用し、品質特性を損なうようなコーディングが出来ないよう強制できる状態がベスト。 強制できない部分は、規律や戒めに頼ることになる。 静的ツールによる、違反の検出 契約による設計 & アノテーション マイクロサービスなどで、実装を完全に隠蔽 コメントとしてヒントをつける 強制や規律の背景を説明するために、コメントは有効。 特に、コメントは設計根拠の説明に有効。 設計ドキュメントへのリンクを貼るだけでも効果的。

やったこと Design It! 7章 パターンで土台を作る 読了 学んだこと ポイント パターンとは パターンを用いるメリット 「アーキテクチャ上の不一致」とは 学び パターンとは、先人の知恵の集合体 パターンを利用することで、以下のようなメリットがある アーキテクチャの選択にかかる時間を大幅に短縮できる パターンの名前で円滑なコミュニケーションをとることが出来る 「アーキテクチャ上の不一致」とは、達成したい品質特性と、選択したアーキテクチャが得意とする品質特性が一致しない現象 そもそもアーキテクチャの選択が不適切 アーキテクチャは適切だが、使用する技術がアーキテクチャに合っていない 所感 パターンを知らなければ、選択することもできない。 まずは、パターンを知るところから。 巨大な泥団子には悪いイメージしかなかったが、意図的に選択するユースケースをしった。 巨大な泥団子もアーキテクチャであり、アーキテクチャである以上トレードオフが存在する...ということだった。 （なお、基本的に良い事はない） "問題重視"と"解決策重視"という二つ観点は考えたことが無く、興味深かった。 メモ 新しい問題に直面した場合、先人の知恵を借りると良い。 つまり、パターンとして整備されたアーキテクチャを選択する。 選択したアーキテクチャを、問題に合うようチューニングする。 この章で扱うこと 有名なアーキテクチャパターンの紹介 アーキテクチャをチューニングする方法 深く触れず、軽く説明する アーキテクチャパターンとは アーキテクチャパターンとは、過去にある問題を解決したことがある、再利用可能な解決策。 パターンを使用すると、以下のメリットがある。 適したパターンを選択できると、アーキテクチャの設計を大幅に短縮できる パターンの名前で円滑なコミュニケーションをとることが出来る レイヤー ある関心事１つを、１つのレイヤーとして実装する。 関心事別にレイヤーを分割し、複数人での共同作業を可能とする。 以下を満たすように実装する。 レイヤー間は疎結合 レイヤ内は高凝集 下位レイヤーは、上位レイヤーに依存しない 言い換えると、下位レイヤーを取り換えても、上位レイヤーが動くよう実装する ポートとアダプター 別名 ヘキサゴナルアーキテクチャ。 核となるビジネスロジックと、その他関心事を分離するパターン。 その他関心事と、取り換え可能なアダプターとして実装する。 アダプターは、ビルド、または実行時に取り換え可能。 これにより、柔軟な動作を可能とする。 パイプとフィルター 一つのデータ操作を、「フィルター」という単位で実装する。 フィルターは、ある一つのデータ処理のみを担当し、処理結果を出力する データをたくさんのフィルターに通して、目的の処理を実現する。 フィルターを並列に処理する場合は「パイプとフィルター」と呼ぶ。 フィルターを直列に処理する場合は「バッチシーケンシャル」と呼ぶ。 一フィルターの処理が重く、次のステージのために結果をファイル化する必要があるような、重たい処理を想定 サービス指向アーキテクチャ 特定の機能を１つ提供するコンポーネントを実装。 このコンポーネントを組み合わせて、任意のサービスを実現するアーキテクチャ。 サービス利用者は、背後にある実装の詳細を知らずに、目的を達成できる必要がある。 旧来は、メッセージバスおよびSOAP経由の通信に依存する形が主流だった。 現在では、HTTP などのメッセージプロトコルを使用して相互に通信する、マイクロサービスの使用を奨励している。 パブリッシュ・サブスクライブ コンシューマー、プロデューサー（パブリッシャー）に分けて実装する。 コンシューマーは、事前に関心のあるイベントのみ購読（サブスクライブ）する。 プロデューサーは、自身が観察しているイベントを観測した場合、イベントを発行（パブリッシュ）する。 コンシューマーは、興味のあるプロデューサーのイベント発行を検知し、即座に目的の処理を実行できる。 共有データ システム全体で共有するデータソースを作成する。 あらゆるコンポーネントがこのデータソースにアクセスして処理を実現する。 RDBとか、オブジェクトストレージとか。 多層 実行時の構造単位でレイヤーを分割する。 レイヤーパターンとは、分割する単位が異なる。 レイヤーパターン : 設計時の要素単位でレイヤーを分割する 多層パターン : 実行時の要素単位でレイヤーを分割する また、分割した層単位で、割り当てるサーバーやプラットフォームを選択できるイメージ。 コンピタンスセンター 専門家チームを雇い、彼らにパターンの定義、ベストプラクティスの確立、サポートツールの開発、教育などを担当してもらう。 システム開発ではなく、開発補助を目的とするパターン。 オープンソース型の貢献 チーム以外の第三者も開発に参加するパターン。 チームは、開発に加え、第三者の変更依頼をレビューし、メインのコードにマージする裁量を持つ。 チームには、書き込み権限を与える 第三者には、変更依頼を提出する権限を与える チームは、第三者の開発を促進するため、以下を実施する スタイルガイドの用意 テスト容易性を考慮した設計 技術に制約を課してプラットフォームを構築 巨大な泥団子 特に定義された要素や関係はない。 開発プラクティスの未熟さ、アーキテクチャへの理解不足などに起因する、保守や拡張が困難な状態を指す。 設計への理解不足に起因するが、設計作業をスキップし、意図的に泥団子を選択することが出来る。 この場合、設計に割く時間を丸々カットできる、つまり開発スピードを一時的に促進できるメリットがある。 泥団子自体は保守困難なため、長期的な開発を視野に入れるなら、早い段階で泥団子を解体する必要がある アーキテクチャ上の不一致を避ける 達成したい品質特性と、選択したアーキテクチャが得意とする品質特性が一致しない現象を、「アーキテクチャ上の不一致」という。 アーキテクチャ上の不一致は、以下の理由で起こり得る。 そもそもアーキテクチャの選択が不適切 アーキテクチャは適切だが、使用する技術がアーキテクチャに合っていない Pub/Subパターンを選択し、データの受け渡しにRDBを選択する アーキテクチャ上の不一致が発生した場合、フレームワークとの戦うことになる。 アーキテクチャ上の不一致を発生させないためにも、適切なアーキテクチャの選択に加えて、アーキテクチャの前提に一致する技術を選択する必要がある。 新しいパターンを発見する 新しいパターンを見つける、以下の2つの方法が知られている 経験した問題たちから、共通の問題を探してパターン化する "問題重視のアプローチ" 問題の解決策たちから、共通の解決策を探してパターン化する"解決策重視のアプローチ" 発見したパターンは、フィードバックを得るために発信しよう。

やったこと Design It! 6章 アーキテクチャを選ぶ 読了 学んだこと ポイント アーキテクチャを適切に選択するにはどうするか 制約の種類 品質特性を考慮してアーキテクチャを選択する 要素に機能的責務を割り当てる目的 変化を見越して設計する 学び アーキテクチャを適切に選択するため、探求プロセスを実施する 問題を解決できるアーキテクチャを列挙する「発散」と、問題に適していない選択肢を排除する「収束」を繰り返す 制約には、「技術的」なものと「ビジネス上」のものがある アーキテクチャに影響を与える制約もある 列挙したアーキテクチャが、解決したい問題に合う品質特性を得意とするか判断する 必須の機能要求を達成したことを確認するために、アーキテクチャ上の要素が負う機能的責務を明文化する 変化に対応できるよう設計する 変更に困難が伴う判断を、可能な限り遅らせる 判断を、アーキテクチャの外に移す アーキテクチャではなく、コーディングレベルの設計で判断を下せるよう、アーキテクチャを決定する 所感 ビジネス上の制約は、技術以外でもなんとかできる可能性がある。 どうにもならないのは、与えらた技術的制約。 前の章にもあったが、勝手に変更できないものと思い込むのは危険。 覚えておきたい。 「品質特性を促進していけるような技術やフレームワークを探求する」は、普段無意識にやっていることだと思う。 例）「スモールにスタートして価値提供を早めたいから xxx を使用する」 これをうまく抽象化した文だと感じた。 「変更に困難が伴う判断を、可能な限り遅らせる」という話は、違う言葉で何度か目にしてきた。 この辺りはよく知られているテクニックなのだと感じた。 メモ 解決したい問題について学ぶほど、よりニーズに合ったアーキテクチャを選択できるようになる。 言い換えると、何も考えず、サイコロを振る感覚でアーキテクチャを選択すると、悲惨な末路を辿る アーキテクチャ上重要な要求を実現するために、トレードオフを加味して複数のアーキテクチャから一つを選択する。 選択肢を広げるために発散させ、決定するために収束させる 「複数のアーキテクチャが存在する」ことを認識するためにも、考えの発散と収束を行う。 発散 : 問題を解決できるアーキテクチャを列挙する 収束 : 合意形成によって、問題に適していない選択肢を排除する 発散と収束を繰り返し、最適なアーキテクチャを模索する。 この過程を、書籍では探求と呼称する。 アーキテクチャ上重要なものを探求する アーキテクトが探求するのは、一般的に以下の分野。 アーキテクチャ構造の全体構成を決定するために、要素とその役割を探求する 要素の責務を明確化する その過程で責務の無い要素を発見した場合、これを排除する 要素が度相互作用するかを決定するために、関係とそのインターフェースを探求する アーキテクチャの要素間を連携させていく手段を探求する REST ? TCP ? 共有メモリ ? GlaphQL ? アーキテクチャが形取る世界を理解するためにドメインを探求する 解決したいドメインの独自用語や概念を説明する 解決したい問題領域を深く理解するほど、適切な要素分割と責務割り当てにつながる 品質特性を促進していけるような技術やフレームワークを探求する 選択した技術の得意分野と、優先したい品質特性が一致する状況が理想 反対に、不一致したり、フレームワークから外れて得意分野を十全に生かせなくなった場合は良くない 出荷を確実にするような構築方法やデプロイ方法を探求する 意思決定を導く視点を得るため、過去の設計を探求する 制約を受け入れる 制約には、「技術的」なものと「ビジネス上」のものがある。 与えられた技術的制約は、受け入れるしかない。 自分たちで判断を下した、技術的制約と化したものは、痛みと引き換えに変更は可能。 ビジネス上の制約は、時としてアーキテクチャに影響を与える 例 : 納期がタイト 並行開発や設計が簡単（または不要）なアーキテクチャ インクリメンタルなデリバリーを促進するパターン 自動化と開発速度を支援する技術を選択 他、速度を上げるために有用な選択肢 上記選択肢を組み合わせる また、ビジネス上の制約は、アーキテクチャの外側で満たすこともできる。 例 : 予算がない 低コストの下請け業者に発注 など 望ましい品質特性を促進する アーキテクチャごとに、品質特性の得手不得手が存在する。 解決したい問題にて重要視する品質特性を明らかにすることで、重要視する品質特性が得意なアーキテクチャを選択できる。 文献を漁り、パターンを調べると良い。 品質特性という観点では、常に「正しい設計」や常に「誤った設計」というのは滅多にない。 「解決したい問題に合うか合わないか」というだけ。 アーキテクチャが、解決したい問題に合う品質特性を得意とするか判断するために、表にまとめると良い。 品質特性 3層 pub/sub サービス指向 ... 可用性 + 〇 + パフォーマンス 〇 - + セキュリティ 〇 - 〇 ++ , + , 〇 , - , -- 左に行くほど得意で、右に行くほど不得意 表にまとめることで、議論のたたき台として機能する。 この時、数字ではなく曖昧な記号を用いること。 数字を用いると、平均や合計といった、数字をいじることに意識が向きかねない 機能的責務を要素に割り当てる アーキテクチャの要素ごとに、責務を明文化し、リスト化する。 これにより、必須な機能要求を達成できることを確認する。 基本的に、機能、要素、責務は、1 : 1 : 1 となる。 例 要素 責務 Web UI WebブラウザでUIを表示し、ユーザー操作を処理する 契約DB 永続ストレージ。契約情報の記録システム 変化に向けて設計する 変化に対応できるようする。 そのために、以下の手段が考えられる 変更に困難が伴う判断を、可能な限り遅らせる 言い換えると、適切な時期に設計判断を下す これにより、判断を遅らせることが出来、得られた時間を、よりよいアーキテクチャや技術を選択するための調査や探求に充てることができる 以下の質問に答えることは、適した時期か判断するのに役立つ 判断しないことが進捗を妨げるか？ 判断は後回しにできない問題を解決するか？ 判断はより多くの選択肢や新しい機会を生み出すか？ 判断を遅らせることで、大きなリスクが発生するか？ 判断の意味を理解し受け入れるか？ 今この判断を下す理由について明確な根拠があるか？ 判断が間違っていた場合に、それを取り消す時間があるか？失敗を許容できるだけのゆとりがあるか？ 判断を、アーキテクチャの外に移す アーキテクチャではなく、コーディングレベルの設計で判断を下せるよう、アーキテクチャを決定する SOLID原則のような、プログラミングパターンから学べる事も多々ある

やったこと Design It! 5章 アーキテクチャ上重要な要求を掘り下げる 読了 学んだこと ポイント アーキテクチャに影響を与える要求とは アーキテクチャの制約をうまく利用する 品質特性シナリオとは ASRワークブックとは 学び アーキテクチャに多大な影響を与える要求に注視し、これを発見するために手を尽くす 適切に選択された制約は、問題を単純化し、アーキテクチャ設計を容易にする 一方で、非常に厳しい制約は、アーキテクチャ設計を必要以上に複雑化する 設計判断（特に開発初期）は、後々制約と化す しかし、制約と化した設計判断は変更できる 与えられた制約か、制約と化した設計判断なのか、区別できるようにする 品質特性の説明するために、品質特性シナリオを書く テスト可能で、測定可能であると良い 特定した「アーキテクチャに多大な影響を与える要求」は、ASRワークブックとして文書に記録する ## 所感 要求の内、アーキテクチャに大きな影響を与えるものに注視するのは、非常に納得感のある話だった。 アーキテクチャを判断する際、優先的に考慮するべき事項として、貴重な情報元になりそう。 与えられた制約か、制約と化した設計判断なのか区別するというのは、あまり考えたことが無かった。 制約とかした設計判断を、勝手に「変えられないもの」と思い込み、「変更する」という選択肢が見えなくなってしまう状態は非常に怖い。 そうならないためにも、与えられた制約か、制約と化した設計判断なのか区別することは重要だと考えるようになった。 初期の設計判断が、後々に制約と化す様はイメージしやすかった。 制約を活用することで選択肢を絞る話、バックログを作成する際にスコープを絞る話に似ていると感じた。 メモ ステークホルダーの要求の内、アーキテクチャに多大な影響を与える要求を アーキテクチャ上重要な要求、（ASR） と呼称する。 アーキテクトは、ASRを明らかにする責務を負う。 ステークホルダーも気付いていない、隠れたASRは無いか ステークホルダーの要求の内、ASRに該当するのか ASRだと判定するには、以下の要求分類について考える。 制約 変更できない設計判断 通常は与えられるものだが、選択することもある 品質特性 影響を与える機能 アーキテクチャにおいて特別な注意を必要とするフィーチャーや機能 その他、影響を及ぼすもの 例） 時間、知識、経験、スキル、社内政治など 制約を活用して設計の選択肢を絞る ここで言う制約とは、 変更できない設計判断を指す。 適切に選択された制約は、問題を単純化し、アーキテクチャ設計を容易にする。 一方で、非常に厳しい制約は、アーキテクチャ設計を必要以上に複雑化する。 制約によって、人、プロセス、予算、スケジュールに関する判断を制限する。 制約の例） 技術的な制約 プログラミング言語の選択(JVM上で動くか、など) OS・プラットフォーム（特定のOSで動くか） ビジネス上の制約 チーム編成 予算・スケジュール 法的制約 制約について、決定事項とその発生源を簡潔にまとめておく。 まとめた制約の例） 制約 発生源 タイプ コンテキスト OSSとして開発しなければならない。 市長 ビジネス 市はオープンデータポリシーを持ち、市民はソースコードにアクセスできなければならない。 ... ... ... ... 制約は一度決定すると、 100%交渉不可能となる。 そのため、受け入れる制約は慎重に決定する。 ソフトウェア開発が進むにつれて、設計判断は（変更が困難という意味で）制約のようになる。 特に、開発初期の設計判断は、開発終盤で大きな制約となる可能性がある ステークホルダーから与えられた制約とは異なり、設計判断は（困難を伴うかもしれないが）変更することはできる。 そのため、「与えられた制約」なのか、「制約と化した設計判断」なのかは区別するようにする。 品質特性を定義する 品質特性とは、ソフトウェアシステムの外部から見える特性とそのシステムの運用に対する期待を表す。 つまり、アーキテクチャ特性。 ASRを考える際、品質特性は常について回る。 品質特性は、システム運用の文脈においては非機能要件と同義と言える。 一方で、品質要求の文脈においては、品質特性は機能的な意味合いもあるため、非機能要件とは呼べない。 また、ソフトウェアアーキテクチャ設計の際は、機能、制約、品質特性を区別した方がよい。 品質特性シナリオとして記録する 品質特性を明確に説明するために、品質特性シナリオを使用する。 品質特性シナリオは、ソフトウェアシステムが特定の環境のコンテキスト内でどのように動作するかを説明したもの。 ◆品質特性シナリオの例 品質特性 シナリオ 優先度 可用性 RFPDBが応答しない場合、システムは障害を記録し、3秒以内に古いデータで応答する必要がある 高 可用性 ユーザーは、RFP検索機能を、年間を通して平均99%の確率で行うことが出来る 高 信頼性 RFPの更新は、変更後24時間以内にアプリケーションに反映される 低 ... ... ... 良い品質特性シナリオは、以下を満たす。 誤解の余地なく、誰でも理解できる文で要求の意図を伝えることが出来る 正確 測定可能 具体的かつ測定可能な応答測定とするように努める ステークホルダーと会話を始める前に、応答測定のたたき台を用意する。 たたき台をもとに、ステークホルダーと議論を重ね、ステークホルダーの共感を呼ぶ応答測定を発見する。 よい応答測定は、テストしやすい。 言い換えると、シナリオを使ったテストを作成できないのであれば、そのシナリオは特定の計測可能な応答測定を持っておらず、詳細化が不十分だと言える。 機能要求の分類を探す アーキテクチャ設計に影響を与える機能要求を、影響力のある機能要求と呼ぶ。 影響力のある機能要求を発見するのはセンスを伴う。 書籍では、以下の手順を紹介している。 アーキテクチャについての現在の考えを要約した概念的なアーキテクチャをスケッチする 大量の機能要求リストから、同じものをグループ化し、代表的な機能要求のみ抽出する 同じアーキテクチャ要素内に実装されている可能性のある機能要求を探す 実装が難しそうな機能要求を探す 価値が高く、優先度の高い機能要求を探す 特定した問題の種類ごとに、概念的なアーキテクチャを辿りながらそれぞれの要求グループをどう達成背売るか示す 実装方法がすぐに示せない場合、ASRである可能性がある それ以外のアーキテクチャに影響するものを見つけ出す 例 知見のある技術 RoRしか経験が無ければ、他のフレームワークの採用は見送られやすい => 設計判断 コスト（金） システムにかける予算が十分になく、貧弱なマシンしか使えないのであれば、それに合った機能や言語・フレームワークを使用せざるを得ない など 必要な情報を掘り下げる ASRは、プロダクトバックログから発見しやすい。 ユーザーストーリーから、品質特性シナリオを作成し、詳細を明らかにしていく。 そのためにも、ステークホルダーと話をする。 ASRの発見に役立つ手法の例 GQMワークショップ ステークホルダーインタビュー 前提リスト ミニ品質特性ワークショップ インセプションデッキ ステークホルダーの目標を理解するためにも、積極的傾聴能力を磨く ASRワークブックを組み立てる 特定したASRは、 ASRワークブックとして文書に記録する。 開発初期は頻繁に更新される。 アーキテクチャがまとまっていくと、更新頻度が減る。代わりに、参照頻度が高くなり、重要な文書に昇華する。 まれに、実行可能なテストやソースコードが、ASRワークブックにとって代わる

やったこと Design It! 4章 ステークホルダーに共感する 読了 学んだこと ポイント 問題を良く理解するために必要なこと ビジネス目標とは ビジネス目標ステートメントとは 学び 問題を良く理解するためには、ステークホルダーを良く理解する ステークホルダーマップを作成することで、関心事別に、重要なステークホルダーを発見できる ビジネス目標とは、「ステークホルダーがソフトウェアを使って達成したいこと」を説明したもの ビジネス目標ステートメントとは、ステークホルダーのニーズに基づき、ソフトウェアに求める要求をまとめたもの 優れたビジネス目標ステートメントは、測定可能で、明確な成功基準を持ち、誤解の余地のない「主体」「成果」「コンテキスト」を含む POV Madlib形式 で記述すると良い ## 所感 POV Madlib形式は、ユーザーストーリーを記述する際によく用いるフォーマットなので、馴染み深かった。 「測定可能で、明確な成功基準を持つ」記載は結構難しいかも？と思ったが、同時に「うまく書けないのは、要求への理解が不十分だからかも？」とも思った。 メモ ソフトウェアで問題を解決するためには、問題をしっかり理解する必要がある。 問題をしっかり司会するためには、ステークホルダーと対話し、ステークホルダーを理解する必要がある。 ステークホルダーに対する理解を深めるほど、解決するべき問題の本質や、もっと別の本当の問題をよく理解できる。 ステークホルダーをよく理解する手段の一つが「共感」である。 適切な人たちと話をする ステークホルダーに当たる人々は様々（ユーザー、金を払う人、開発者、運用者など）。 通常、ステークホルダーが一人ということはそうそうない。 「ユーザー」や「開発者」に相当する人間は複数人存在する...という意味 書籍では、このことを際立たせるために「ステークホルダーグループ」という言葉を使用している ステークホルダー一個人の要求を理解するのではなく、ステークホルダーグループの要求を理解することが重要。 ステークホルダーマップを作る ステークホルダーの関係や相互作用を理解する手段として有効なのは「視覚化」。 関係や相互作用を視覚化するために、ステークホルダーマップを作成すると良い。 ソフトウェアシステムに関与する（または影響を受ける）人々を示すネットワーク図 ステークホルダーマップから、ある関心事について話し合うべき最も重要な人々は誰なのか、発見できる。 ビジネス目標を発見する ビジネス目標とは、「ステークホルダーがソフトウェアを使って達成したいこと」を説明したもの。 ビジネス目標を起点に、「品質特性」やそのトレードオフ、技術的負債、開発する機能の優先順位といった会話が発生することになる。 ステークホルダーのニーズに基づき、ソフトウェアに求める要求をまとめたものを「ビジネス目標ステートメント」と呼称する。 ビジネス目標ステートメントを記録する 優れたビジネス目標ステートメントは以下の通り。 測定可能 明確な成功基準を持つ 説明文に、以下の3要素を含む 主体 ... 「誰が」に相当 成果 ... 「成し遂げたいこと」を相当 コンテキスト ... 「成果」のより深い理解を促進する、問題の背景 重要性 「必須」「あるとよい」ぐらいで十分 ビジネス目標ステートメントは POV Madlib 形式で書くと良い。 POV Madlibの例 XXX市市長は、調達予算を30%減らす必要がある。 なぜなら、彼は必要不可欠な部門の予算削減を避けたいと思っているからだ。 アーキテクトは、ビジネス目標を明らかにするために、以下を行う。 ステークホルダーと密にコミュニケーションをとる 彼らが目標をうまく説明できない場合は、手助けをする

やったこと 記事執筆 https://zenn.dev/t0mmy/articles/our-amplifys-knowledge

やったこと 記事執筆 https://zenn.dev/t0mmy/articles/private-link-is-great 学んだこと vscode の drawio integration 拡張機能の使い方学んだ .drawio.png 拡張子の存在を知った AWS VPC ルーティング周りの挙動を再確認した

やったこと 書籍 「Design It!」 2章 読了 学んだこと ポイント デザイン思考とは デザイン思考 4つの原則 4つのデザインマインドセット 学び デザイン思考とは、人間に焦点を当てた、問題解決のアプローチ 設計判断に影響を与える人々を特定し、彼らに焦点を当てることで、解決すべき本質的な問題を発見する デザイン思考には、「人間性」「曖昧性」「再デザイン」「触感性」4つの原則が存在する デザインに当たっては、4つの異なるデザインマインドセットが存在する 各マインドセットごとに、プラクティスが存在する プラクティスを適用することで、新たな学びを得ることが出来、次のフィールドループに活用できる 気づき 「アーキテクチャは他の人と共有できなければ、それを形にすることはできない」の辺り アーキテクチャに限らず、アイデア全般にも同じことが言えそう 思い描いたアイデアを第三者に（伝わるように）説明できなければ、理解をえられず、支援も期待できない デザインマインドセットの「評価」は、ユースケースごとに実施すると良いかも？ ## メモ アーキテクチャを設計するために、解決すべき問題を明らかにし、解決策を探求する。 これらに役立つ手法が デザイン思考 と呼ばれる手法。 デザイン思考は、人間に焦点を当てた、問題解決のためのアプローチ。 設計判断に影響を与える人々を特定することで、解決すべき本質的な問題が見えてくる。 2.1 デザイン思考の4つの原則 デザイン思考は、影響を受ける人々の視点から問題や解決策を考える手法。 デザイン思考は、以下4つの普遍的な原則を持つ。 人間性の規則（The Human Rule） すべてのデザイン活動は究極的には社会的な性質を持つ 曖昧性の規則（The Ambiguity Rule） デザイン思考者は曖昧性を保全せねばならない 再デザインの規則（The Re-design Rule） すべてのデザインは再デザインである 触感性の規則（The Tangibility Rule） 手で触れられるアイデアを作ることは、常にコミュニケーションを促進する 上記4原則は、プログラム設計、UI設計をはじめ、ソフトウェアアーキテクチャなど、幅広い分野に応用できる。 人間のための設計 人のためにソフトウェアを設計する そして、人と共に設計する エンドユーザーと同じく、ステークホルダー全員を大事にする アーキテクトは、チームと協働してアーキテクチャを設計する 象牙の塔のアーキテクトになってはならない 全ての設計判断は、他の人々に理解され、共有できなければならない 曖昧さを保つ アーキテクトは設計しすぎないこと（必要最小限のアーキテクチャ）。 優先すべき品質特性をどうやって満たすか、品質特性を促進sヌルためにリスクをどう減らすかだけを示す それ以外の設計判断はすべて、後続の設計者にゆだねる つまり、責任を持てる限りにおいて設計判断を遅らせる こうした曖昧さは、後々に選択の余地を残すことにつながる。 設計とは再設計である アーキテクトは、過去の知見やパターンを最大限活用する。 過去の知見やパターンを活用（改良）して、現在の問題の解決に役立てる。 アーキテクチャをタンジブルにする アーキテクチャを誰かと共有する際は、コード以外の方法で形にすること。 設計の根拠、設計判断が及ぼす効果への理解を促進し、よりよい議論につなげるため コード以外の方法には、図、プロトタイプ、モデル作成、制御フローの図示など、様々な手法が検討できる。 アーキテクチャを他の人と共有できなければ、それを形にすることはできない。 デザインマインドセットを身に着ける デザインに当たっては、異なる4つのマインドセット（視点？）がある。 理解～問題を理解する ステークホルダーから情報を収集し、問題の理解に努める 言い換えると、要求を理解するよう努める 同時に、ビジネス目標と品質特性を調査し、優先順位とトレードオフを把握しなければならない 探求～アイデアを探求する 最適な品質特性と構造の組み合わせをひたすら探求する 作成 ～ 形にする アイデアを共有する、試すために、アイデアを形にする 評価～妥当かを評価する ユースケースや実験、リスク調査などを通して、設計判断を評価する 評価を行い、現在の理解を基準に設計判断か妥当かどうか判断する 各マインドセットには、それぞれプラクティスが存在する。 プラクティスを適用することによって、新たな学びを得ることが出来、次にフィードバックループ デザインマインドセットは、強力なフィードバックループを持つプロセスを前提としている。 Think、Do、Check 日々の変化をいち早く察知し、状況に対応するために、素早いフィードバックループを持つ設計アプローチが必要となる。 本書では、素早いフィードバックループとして、Think-Do-Checkサイクルを紹介している。 Think-Do-Check サイクルでは、以下を繰り返す。 Think ... 考えるステップ。ビジネス目標、品質特性、トレードオフ、リスクなどを考える Do ... 実行ステップ。モデルやプロトタイプ作成、計画実行など Check ... Do ステップで達成したことを批評的に検証し、次のアクションを決定する Check で得られた洞察から、次に何をするべきかを得て、Thinkステップに戻る 一つのマインドセットに焦点を当てて、このサイクルを回す。 マインドセットを適用する デザインマインドセットは、任意の順で実行できる。 そして、マインドセットは頻繁に移り変わる。 一度の会話で、複数回マインドセットを切り替えることもある 四つのマインドセットを区別し、認識できるようになること。 すると、意図的にマインドセットを切り替えることが出来るようになる。

やったこと 学んだこと ポイント ソフトウェアアーキテクトとは どんな人？ 何をする人？ アーキテクチャの基本構造3つ 品質特性とは 学び ソフトウェアアーキテクトは、広い視野を持って、技術以上のことを扱う 構造にもいくつか種類がある 「構造の種類が異なる」ことを認識できると、様々な性質を考える際に役立つ ## メモ 1.1 ソフトウェアアーキテクトが行うこと エンジニアリングの観点から問題を定義 ステークホルダー（プロダクトマネージャーやプロジェクトマネージャーなど）と協力し、ソフトウェアのビジネス目標と要求を定義する。 ステークホルダーと協力し、ソフトウェアのビジネス目標と要求を定義する システムに対する品質特性を定義する アーキテクチャに影響を与える設計上の制約やフィーチャーに注視する システムを分割し、責務を割り当てる 以下の効果を得るため、ソフトウェアシステムを、責務別に分解する。 品質特性をはじめとするシステム要求を満たす戦略を立てられるようになる より開発しやすくなる 小さいものほど、設計、開発、テストなどが容易になる 広い視野を持って全体に目を向ける システム全体について考える場合、理想と現実のバランスを見極める（≒トレードオフについて考える）必要がある。 設計判断が、ソフトウェアに関わる要素（ユーザー、開発・運用チーム、ハードウェア、開発目的）に与える影響を広くとらえ、うまくバランスを取ることが求められる。 品質特性間のトレードオフを決定する 全ての品質特性を満たすことは非現実的。 そのため、何かをあきらめる必要がある（≒トレードオフを考える）。 例）可用性のためにハードウェアを複数購入すると、コストをあきらめることになる コストを引き換えに、可用性をとった形 こういったトレードオフを把握し、最適なトレードオフを、ステークホルダーと共に選択する。 技術的負債を管理する 技術的負債 ... 現在の設計と、継続的に価値を届けるために必要な設計とのギャップ 開発チームは、必要に応じて技術的負債を負う（リリースを早めるため、など）。 そして、定期的に負債を返済する。 定期的に負債を返済するために、アーキテクトは、技術的負債を適切に管理する。 また、アーキテクトは、技術的負債を可視化する。 これによって、ステークホルダーは、技術的負債に対してアクションの必要性を判断できる。 チームのアーキテクチャスキルを高める アーキテクチャの専門家として、チームのアーキテクチャスキル向上に努める。 適切なタイミングで、 ペア作業や共有ドキュメント作成を通して、 建設的な批評を行う これにより、チームはアーキテクチャを理解できるようになり、優れたソフトウェアシステム開発に貢献する。 1.2 ソフトウェアアーキテクチャとは何か システムのソフトウェアアーキテクチャとは 望まれる品質特性やその他の性質を促進するためにソフトウェアをどう構成するかということに対する、重要な設計判断が集まったもの 「品質特性を促進する」とは、それがソフトウェアシステムの中に現れるよう働きかけることを指す。 品質特性の一つが「コスト」であれば、「納期に間に合い、予算内で、残業に頼り過ぎない」というのが正しいアーキテクチャと思われる 基本構造を定義する 「要素」 ... ソフトウェアの基本構成単位 「関係」 ... 「要素」が役割を全うする際にどのように連携するかを示したもの 「構造」 ... 「要素」と「要素」を、「関係で繋いだもの」 ![[Drawing 2023-12-17 12.20.50.excalidraw]] 要素と関係の分類には、以下の例がある。 概要 要素の例 関係の例 モジュール 設計時に現れる構造 クラス、パッケージ、レイヤ、モジュール、構成ファイル、DBなど ～を使用する、～の使用を許可する、～に依存する コンポーネント&コネクター (C&C) 実行時に現れる構造 オブジェクト、コネクション、スレッド、プロセス、層など ～を呼び出す、～を購読する、～をパイプする、～を戻す 割り当て （対応構造） 上記構造群の対応を示す構造 サーバー、センサーラップトップ、LB、コンテナ、チーム、人 ～上で実行する、～内で実行する、～の責務を負う、～を開発する、～を格納する 異なる種類の構造を知っていると、システム内で必要となる様々な性質を考える際に役立つ。 モジュール構造を使って、テスト容易性や保守性について考えることが出来る C&C構造は、可用性やパフォーマンスなどの実行時の問題を考えるのに役立つ 構造は、システムの形状を決定する。 システムの形状は、利用者が体験する部分であり、重要である。 品質特性を見通す 品質特性とは ステークホルダーがソフトウェアシステムの良さを判断するための、外部から見える特徴。 例) 拡張容易性、可用性、保守性、テスト容易性 など（≒アーキテクチャ特性） ステークホルダーが望む、ソフトウェアシステムが満たすべき品質特性を、設計に組み込んでいくことになる。 そこには、当然トレードオフが存在する。 1.3 チームのアーキテクトになる アーキテクトは、チームの役割や名刺上の肩書ではなく、心の持ち方。 ソフトウェアシステムの構造に影響を与える決定を行う人であれば、誰しもアーキテクト代行である。 プログラマーからソフトウェアアーキテクトへの道 アーキテクトは、様々な開発経験を通じて、技術的責任の範囲を広げる。 アーキテクチャに対する責任が増えると、徐々にコードに触れる機会が減少する。 しかし、決して「コードを書かない」状態になってはならない。 今まで携わってきたプロジェクトに対して、以下の問いに答え、振り返る機会を設ける。 ステークホルダーは誰だったか、主要なビジネス目標は何だったか ビジネス目標を満たすために取られた全体のソリューションはどのようなものだったか どんな技術に取り組んだか 最大のリスクは何だったか、それらをどのように克服したか 今もう一度やり直すとしたら、どのようにするか 振り返り、学びをまとめよう。 1.4 素晴らしいソフトウェアを作り上げる ソフトウェアアーキテクチャの手助け 大きな問題をより小さく、より管理しやすい問題へと変える 人々の協働のやり方を示す 上手なコミュニケーション方法の提案 複雑な問題について会話するための語彙を提供する 話していることを互いに理解するために、基本思想や語彙を提供する フィーチャーや機能以外のモノ（特に品質特性）にも目を向ける コストのかかる間違いを避けるのに役立つ 後々大きな問題を引き起こす可能性のある、難しい部分を発見する 変化への柔軟な対応を可能にする

やったこと 書籍 「Design It!」 3章 読了 学んだこと ポイント デザイン思考を使用した、解決策の模索方法 デザインスイートスポットとは リスクを活用する 学び 適切なデザインマインドセットを選択し、リスク軽減策発見に役立てる デザインスイートスポットとは、アーキテクチャ設計に費やすべき、最も費用対効果の高い時間 リスクを以下のように活用する リスクを明らかにする 頭をよぎった「嫌な予感」を、「条件」と「結果」に落とし込む デザインマインドセットを使用して、リスク軽減策を発見する リスクを許容範囲内まで軽減出来たら、アーキテクチャ設計に専念する メモ デザイン思考を使用することで、実験・検証を繰り返しつつ、複雑な問題の解決策を模索できる。 ソフトウェアシステムの持つリスクを考えることで、より幅広いデザイン戦略の一環としてデザインマインドセットを選ぶ方法について学んでゆく。 3.1. 満足のいく設計を見つける アーキテクチャを設計する前に、ソフトウェアシステムで解決したい問題を定義する。 その問題を完璧に定義することは不可能に近い。 そのため、最適で合理的な設計を追求する代わりに、必要最低限のアーキテクチャを発見することを目指す。 必要最低限のアーキテクチャは、以下の活動を通して発見していく。 解決策を実験とみなす 問題の解決策を検証する実験と考える リスクを減らすことに専念する アーキテクトは、失敗する可能性を常に考慮して設計する アーキテクチャの失敗は、全ての失敗につながるため 問題を単純化する 問題を単純化すると、解決策も単純化する 定型問題（既知の解決策を利用できる問題）に当てはめることで、先人の知見を活用できるようになる 素早く繰り返し、素早く学ぶ 問題と解決策を同時に考える 問題は、常に解決策を念頭に置いて定義される ... とのこと 問題を理解するためには、解決策を探る 解決策をうまく探るためには、問題に対する理解を深めなければならない => 問題と解決策を同時に考える必要がある 3.2 どのくらい前払いの設計を行うかを決める 十分なアーキテクチャへの投資は、将来の修正コスト削減につながる。 一方で、アーキテクチャ設計に時間を割きすぎることは、実装時間を遅らせ、結果的に価値提供も遅れることになる。 ここで、「アーキテクチャ設計に費やす最適な時間いくらか？」という問題が発生する。 最適な時間は、ソフトウェアシステムの大きさと要求の多様性に応じて変化する。 この時間のことを。デザインスイートスポットと呼ぶ。 デザインスイートスポットを見つける スイートスポットは、アーキテクチャ設計と修正作業時間の損益分岐点。 研究によって、プロジェクトスケジュールの約20%未満辺りが最適と言われている。 以下 は、100 日間の初期開発スケジュールを想定した数値 アーキテクチャに費やす日数 修正に費やす日数 合計のスケジュール日数 - 5 38 143 17 21 138 ★ 33 7 140 また、以下のことが分かっている。 ソフトウェアシステムが大きくなるほど、アーキテクチャ設計への投資効果が大きくなる 小規模のソフトウェアシステムでは、アーキテクチャ設計への投資効果がほとんどない これは、コードを書きなおすほうが早いことを意味する アーキテクチャ設計への投資を怠ると、後半の修正コストが膨大となる アーキテクチャ設計へ投資するほど、必要な手直しは少なくなる スイートスポットは、ソフトウェアシステムの大きさ、複雑さに加え、要求の変動制（要求が、将来的に変更する可能性）にも依存する。 変更される可能性が高い場合、判断を遅らせる。 3.3 リスクに道案内させる リスクは、成功を妨げるかもしれないものを測るための優れた指標。 アーキテクチャに専念すべきタイミングを決定する指標として、リスクを使用できる。 つまり、十分にリスクを軽減できたタイミングで、アーキテクチャに専念する まとめると、以下の通り リスクを明らかにし、大きな問題を起こすリスクを特定する 特定したリスクを軽減するために、デザインマインドセットを選択し、対応方法を探す うまくリスクを軽減出来たら、パッシブデザインへと移行し、アーキテクチャに専念する 条件と結果を明らかにする リスクを、「条件」と「結果」という二つの要素で説明する。 条件 : 事実である「何か」 結果 : 発生する「よくないこと」 明らかとなった「条件」と「結果」は、リスクに対して次のアクションを決定する良い情報源となる。 リスクを使用してデザインマインドセットを選択する 設計を通じて、リスクを軽減する。 「嫌な予感」をうまく「条件」と「結果」に落とし込むことが出来れば、設計の助けとなる。 デザインマインドセットは、リスクを軽減する戦略立てに役立つ。 以下の問いかけを参考に、試すべき適切なマインドセットを判断する。 問い どこにリスクがあるか 試すべきマインドセット ステークホルダーや他のアクターをもっと深く理解するべきか 問題 理解 十分な代替案を検討したか 解決策 探求 ステークホルダーは、設計コンセプトを十分理解しているか、また、アーキテクチャを確認できているか コミュニケーション 作成 設計判断を行う必要があるか 設計判断や設計の適合性 評価 リスクが軽減されたら、パッシブデザインへと移行する リスクを十分軽減できたら、アクティブデザインからパッシブデザインへと移行する。 アクティブデザイン ... リスクを減らすべく、フィードバックループを積極的に回す パッシブデザイン ... 稼働しているアーキテクチャを観察し、必要に応じて措置を講じる パッシブデザインにて、アーキテクチャから重大なリスクを確認した場合、設計における仮定が誤っていたことを示す。 この場合、再びアクティブデザインに切り替え、新しい仮定に基づいてアーキテクチャを調整する。 3.4 設計計画を立てる アーキテクチャに費やす時間全般について計画を立てる。 分析は前もって行うか？ 後々の変化を予期出来ているか？ いつコードを書き始めるべきか？ 良い設計計画は、期待を設定し、詳細を説明する者になっている。 また、設計計画は正式なスケジュールである必要はない。 インセプションデッキのような、さっと作成できるドキュメントを使用して、計画を形にする。 設計を止める条件 必要な設計成果物 アーキテクチャを文書化する方法を決定し、全員に伝達する タイムライン プロジェクトスケジュール内の重要なマイルストーンを記述する 少なくとも、アーキテクチャ上重要な要求のレビュー、設計案のレビュー、評価実施のマイルストーンは含めること 上位リスク リスク上位を設計計画に組み入れる 様々なタイミングで、リスク上位を見直す 概念的なアーキテクチャ設計 潜在的な解決策から始める

やったこと API デザインパターン 24章 バージョン管理と互換性 読了 学んだこと ポイント 互換性の意味 後方互換性の意味 バージョン管理の手段 バージョン管理のトレードオフ 学び 「互換性」は、二つの異なるコンポーネントが、互いに正常にやり取りできるかどうか 新バージョンのAPIが、旧バージョンAPIを使用したコードでも問題なく動作する場合、後方互換が有るという 後方互換のある変更を、既存のバージョンに加える 後方互換のある変更を、新バージョンとしてリリースする 後方互換の無い変更を、既存のバージョンに加える（基本的に選択しない） 後方互換の無い変更を、新バージョンとしてリリースする コードを変更するときに、後方互換を維持するか議論する必要が生まれる 機能追加、バグ修正など バージョン管理の手段 永続的な安定性 アジャイルインスタビリティ セマンティックバージョン管理方式 バージョン管理のトレードオフ 細かさと単純さ 安定性と新機能 満足度と偏在度 メモ WebAPIの更新は難しい。 API利用者に損害を与えることなくWeb APIを変更するにはどうしたらよいか。 「利用者に対応してもらう」は受け入れてもらえない。 「そもそも変更しない」も不可能に近い。 セキュリティや法律の問題で改修を余儀なくされる、など ではどうするか。 概要 チェックポイントやバージョンを導入し、バージョン別にデプロイできる。 利用者に問題を引き起こす可能性のある変更は、別バージョンとしてデプロイする。 バージョン管理の一番の目的は、API利用者に多くの機能を提供しつつ、不便さを最小限に抑えること。 互換性 二つの異なるコンポーネントが、互いに正常にやり取りできるかどうかを示す。 Web API の場合、クライアント、とサーバー間の通信を指す。 APIサーバーに変更を加えても、クライアント側で期待通りの動作をするのであれば、変更前と変更後のバージョンには互換性がある、と言える。 では、互換性（ここでは後方互換性）を持つかどうか、言い換えると、クライアントコードに影響を与えるかは、どう判断するか。 後方互換性を定義する 「後方互換性を有する」を一意に定義することはできない。 言い換えると、API利用者の期待によって変わりえる。 そのため、API提供者側で、APIの「後方互換性」を定義する必要がある。 後方互換性を考える必要がある、一般的な問題を見ていく。 機能追加 機能追加の際、既存のバージョンを拡張するか、新バージョンを発行するか。 新機能を、どう実装するか。 既存のリソースのフィールドを増やす形で実装する メモリがシビアなIoTなどでは、ちょっとしたデータの追加がクラッシュに直結する可能性がある 新しいリソース、またはメソッドとして実装 既存のリソースに影響はない API利用者が、全リソースに対して何らかの処理（バックアップなど）を行っている場合、新規リソースの追加は処理対象の漏れにつながる 既存のリソースに影響を与えるような、リソース、メソッドの新規追加 利用者に新機能の学習を強いることになる いずれの方法でも、問題は残る。 バグ修正 バグ修正によるリリースも、場合によっては後方互換性を考慮する必要がある。 明確なエラー（500系エラーの修正）は、後方互換性がある。 一方で、400エラーを想定したところ、無意味な値 ({} など)を返していたようなエラーは難しい。 API利用者が、 {} が返ってくることを想定したコードを書いている可能性は非常に高い もし 400 エラーを返すようにすると、 {} を期待した既存のコードは動かなくなる つまり、400エラーを返すような修正は、後方互換性が無い 修正方法に正解はなく、「場合による」としか言えない。 強制的な変更の取り扱い 外的要因により、APIの変更を余儀なくされることがある。 例）GDPR導入によるGDPR対応 この時、既存のバージョンを修正するのか、新バージョンとしてデプロイするのか選択する余地がある。 この判断にも正解はなく、「場合による」としか言えない。 新バージョンをデプロイし、徐々に新バージョンへ移行するよう促す 既存のバージョンを修正し、「GDPR施行後、未対応の旧バージョンが使用される」というリスクをシャットアウトする 大事なのは、API利用者の負担を極力減らしつつ、義務付けられた変更を行うこと。 可能な限り事前通知を行い、利用者の作業を最小限に抑え、利用者への影響を少なくすること。 表からは見えない変更 性能の最適化、提供するサービスの精度向上など。 後方互換性があると見なされることが多いが、無いという方向でも成り立つ。 非同期処理を行っていたAPIのレスポンスが、突如 0.1秒未満になると、同期処理が現実味を帯びる 機械学習モデルの変更によるレスポンスの大幅な変化 利用者次第で、後方互換性有とも無しともとられる。 セマンティックスの変化 ここで言う「セマンティックス」は、「動作の変更」や「APIの概念の意味」を指す。 導入する事柄で評価が大幅に変化する。 大きな影響の例 : 新しい権限モデル導入による動作の変化 小さな影響の例 : 配列の順序 既存の利用者と、変更が利用者のコードに与える影響を調べ、利用者に受け入れられるか検討すること。 検討によって、変更を既存のバージョンに組み込むか、独立した新バージョンとしてデプロイするか決定する。 実装 新バージョンの導入方法について学ぶ バージョンの名前は？ 旧バージョンは、非推奨となるまで、何日ほど存続させるか？ 永続的な安定性 後方互換性のない必要が生じたときに初めて、バージョン管理方式について考えるやり方。 つまり、後方互換性のある変更は、常にバージョンNにマージされる。 バージョン管理の仕組みや方式を全く考慮しない場合に発生しやすい。 無意識に思いつきがちな方式であり、安定する傾向にある。 一方で、細かな変更が重要となるAPI（IoT用など）では受け入れられない。 IoTは、ちょっとしたデータの追加でメモリオーバーフローが発生しかねないため、特定のAPIバージョンでフリーズする機能を必要とする また、後方互換のない変更が増えると、たくさんのバージョンが発生する。 アジャイルインスタビリティ それぞれのAPIバージョンに、ライフサイクルを示すステータスを付与する方式。 Preview => Current => Deprecated => Deleted Preview ステータスの API バージョンは、開発者が自由に変更できる。 API利用者は、明日にも振る舞いが変わること理解する必要がある。 完成されたものになると、Current ステータスへ移行する。 必須となるパッチ当てやバグ修正だけを行い、互換性のない変更は実装しない。 互換性のない変更は、次のバージョンに追加していく。 古いバージョンのAPIを削除したい場合は、まず Deprecated へ移行し、削除時期を周知する。 時期が来たらAPIを削除し、ステータスを Deleted へ移行する。 Currentステータスのバージョンと、 Previewステータスのバージョンは、常に一つだけ。 これにより、有効なバージョンの数を最小限に抑えつつ、継続的な改良を進めるための強制力として機能させることが出来る。 どのバージョンも、将来的には Deprecated から Deleted へ移行する点が欠点。 つまり、現行バージョンがずっと機能し続ける保証は全くない。 新機能が待ち望まれ、安定している期間が短くても問題ないケースで有効。 反対に、長期的な安定性が求められ、新機能もあまり重要ではないようなケースでは使いにくく感じる。 セマンティックバージョン管理方式 X.Y.Z X : メジャーバージョン。後方互換性のない変更を加える時にインクリメントされる Y : マイナーバージョン。後方互換性のある変更を加える時にインクリメントされる Z : パッチバージョン。後方互換性のある、主にバグ修正などに伴う変更を加える時にインクリメントされる バージョンが膨大に増え、利用者を混乱させる可能性がある点が欠点。 利用者はできるだけ長い間、特定の非常に細かいバージョンを使い続けたがる傾向にある。 また、全バージョンが永遠にサポートされるわけではない。 非推奨ポリシーを設け、アジャイルインスタビリティのように Deprecated => Deleted となることもある。 利用者は最新バージョンを追求することも、特定のバージョンを使い続けることもできる。 トレードオフ 細かさと単純さ きめ細かなバージョンを提供するか、後方互換性を維持した少数のバージョンを提供するか、のトレードオフ。 細かさ : きめ細かなバージョンを提供する 特定の安定バージョンをずっと使い続けたい利用者には刺さる 一方で、新規API利用者には、どのバージョンを使えば良いのか惑わせることになる 単純さ : 後方互換性を維持した少数のバージョンを提供する バージョンが少ないため、最適な選択肢を選びやすい 一方で、特定の安定バージョンを求める利用者には刺さらない 安定性と新機能 APIに変更を加える機会を減らして長期間安定させるか、APIにどんどん機能を追加して、一定の期間だけ安定させるか、のトレードオフ。 満足度と偏在度 利用者は多岐にわたるため、API提供側のポリシーが、全利用者に受け入れられる可能性は非常に低い。 一部の利用者の満足度を最大化する方向で意思決定を行うのか、全利用者の使い勝手を最大化する方向で意思決定を行うのか、のトレードオフ。 利用者を「使えない」「不満足」「大丈夫」「満足」の4つに分類すると、以下の通り。 一部の利用者の満足度を最大化する方向 : 「満足」利用者を最大化する事に重きを置く。代わりに、「使えない」「不満足」が増える 全利用者の使い勝手を最大化する : 「大丈夫」利用者を最大化することに重きを置く。代わりに、「満足」が減る 扱うこと バージョン管理とは 互換性とは 後方互換性をどう定義するか バージョン管理手法に伴うトレードオフ Web API のための一般的なバージョン管理手法の概要 まとめ バージョン管理は、API設計者が時間の経過とともにAPIを変更・進化させながら、できる限り利用者に不利益を与えず、多くの改良を提供するためのツール 互換性とは、あるバージョンでのAPIに対して書かれたコードが、別のバージョンに対しても引き続き機能する事を意味する 新しいバージョンは、前のバージョンに対して書かれたコードが期待通りに動作する場合、「後方互換である」という API設計者が利用者の期待をどのように定義するかは、解釈によって変わる 一見無害に見えること（バグ修正など）が後方互換性のない変更に繋がったりする APIの利用者が利用者の期待をどのように定義するかは、解釈によって変わる

やったこと API デザインパターン 25章 論理削除 読了 学んだこと ポイント 論理削除とは 論理削除の実装方法 論理削除実装の際に考えるべきこと 学び 論理削除とは、後から復元可能な削除方法 以下の方法で実装する 論理削除フラグを使って、削除状態を制御 リソースのステータスに 削除ステータスを追加する 論理削除は標準の delete メソッドで実装。ほかにも、以下を実装する 復元用の、undelete カスタムメソッド 物理削除用の expunge カスタムメソッド 論理削除実装の際は、期限切れや参照整合性など、いくつか追加で考えることがある 標準の delete メソッドに適用される参照整合性ガイドラインは、論理削除されたリソースにも同様に適用する 気づき メモ 標準の delete メソッドの目的は、リソースを削除する事。 この時、 物理削除だけではなく、ゴミ箱のように復元できるような削除方法も選択できる。 復元できるような削除方法である「論理削除」について見ていく。 対象とする問題 ユーザーは、何らかの理由で削除を取り消したい場合がある。 フィルタリングのミス （APIの削除リクエストを叩くような）スクリプトのミス こういった状況を想定し、復元できる手段を残す。 概要 論理削除を実装する主な手段は以下の通り。 論理削除を示す deleted フラグ 既存のリソース状態を示すパラメータに、 deleted を追加する 実装 論理削除は、標準の delete メソッドに実装することになる。 論理削除実装に伴い、以下も必要となる。 物理削除用の expunge カスタムメソッド 復元用の undelete メソッド 他の標準メソッドの動作を変更 例 標準の list メソッドにて、 論理削除されたリソースを除外する 削除済みの指定方法 boolean型のフラグを使用する方法 デフォルトは false 状態フィールド リソースの状態を示すプロパティに、論理削除ステータスを追加する方法 論理削除を取り消すとき、どの状態へ遷移させるかが問題となる 標準メソッド修正する 論理削除の実装に合わせて、必要に応じて、標準メソッドを変更する。 GET 論理削除情報も含め、通常通りリソースを返却する。 つまり、論理削除されたリソースへの GET で 404 を返してはならない 「IDを指定して論理削除されたリソースの GET をリクエストする」のは、リソースの削除状態を確認するという目的と考えられるため LIST デフォルトでは、論理削除されたリソースは除外して、リソース群を返却する。 論理削除されたリソースも含めたリソース群を要求できるようにしたい場合、リクエストインターフェースを拡張することになる。 includeDeleted フラグなど。 フィルタリングで実装しないこと。 全ての LIST がフィルタリングをサポートしているわけではない フィルタリングは、結果として、常にデータを減らすことになる includeDeletedフラグは、反対にデータを増やすことになる API の目的に一貫性と明確さを保つ意味合いもある。 DELETE 論理削除に合わせて、 フラグを変更する処理に変更する。 論理削除済みのリソースに対して DELETE を要求された場合は、命令型と宣言型（7章）のどちらを取るかという、APIの一貫性に従う。 一般的には、期待通りにリクエストを実行できなかったことを示す、412エラーとする 復元する undelete カスタムメソッドを用意し、論理削除フラグを変更する。 未削除のリソースに対して undelete を要求された場合は、命令型と宣言型（7章）のどちらを取るかという、APIの一貫性に従う。 一般的には、期待通りにリクエストを実行できなかったことを示す、412 エラーとする 物理削除する expurge カスタムメソッドを用意し、物理削除を実装する。 未削除のリソースに対して expurge を要求された場合、 削除フラグの如何に関わらず削除してしまう。 期限切れ 定期的にゴミ箱を空にしたい場合などに使用する。 論理削除をサポートするリソースに、有効期限を表すフィールドを設ける。 論理削除状態以外の状態のとき、有効期限を表すフィールドはNullになる。 参照整合性 論理削除されたリソースは、他のリソースから参照可能かどうか、決めておく必要がある。 正解はなく、他のAPIと同じルールを適用することが重要。 参照整合性を保つために削除を禁止しているのであれば、同じ制約を論理削除にも課す ... など バージョンを介した論理削除の追加 後から、論理削除機能を追加する場合、どうやって安全に機能を追加するか。 結論は、正解はなく、状況による。 後方互換性が無いと判断される可能性を考慮し、論理削除実装の際はメジャーバージョンのアップを考慮しておくと良い。 扱うこと 倫理削除とは？それがいつ有効か？ リソースに削除マークを付け、実際には削除されていないことを示す方法 論理削除をサポートするリソースの標準メソッドに必要な修正 論理削除されたリソースの削除を取り消す方法 削除されたリソースを永久に削除（物理削除）する方法 参照整合性の管理 まとめ 論理削除とは、リソースを削除済みとしてマークする機能 deleted フラグで表現することが多い 既にリソースの状態を表すパラメータを導入しているのなら、そこに deleted を追加するのも有り 論理削除をサポートする標準メソッドは、いくつかの小さな変更が必要 論理削除されたリソースに対して get をリクエストした場合、404を返してはならない 論理削除されたリソースには、復元用の undelete カスタムメソッド、 物理削除用の expunge カスタムメソッドを提供する 標準の delete メソッドに適用される参照整合性ガイドラインは、論理削除されたリソースにも同様に適用しなくてはならない 参照されるリソースのカスケード削除など 一貫性を維持するため

やったこと API デザインパターン 28章 リソースリビジョン 読了 学んだこと ポイント リビジョン機能とは何か どうやって過去の状態に戻るか リビジョンを作成する方法 リビジョンを操作する方法 子リソースをもつリソース（つまり親リソース）のリビジョンの扱い 学び リビジョン機能とは、リソースを過去の状態に戻す機能 リソースに、リビジョンを一意に識別できる 識別子を付与する リビジョンの作成方法には、暗黙的な作成と、明示的な作成の二つがある 暗黙的な作成では、何らかのイベントを条件に、API側で自動的にリビジョンを作成する 明示的な作成では、リビジョンを作成するカスタムメソッドを提供し、利用者の判断でリビジョンを作成してもらう リビジョンの操作 リビジョン取得機能は、標準の GET メソッドを拡張する形で提供する リビジョンの復元、削除機能は、カスタムメソッドにて提供する リビジョンの復元は、復元したいリビジョンのリソースを、最新のリビジョンとして新規作成することで実現する 復元の際、リソースの履歴を削除したり変更したりしてはならない ビジネス要求次第では、子リソースもリビジョン管理対象に含める ただし、APIの複雑化や、より多くのストレージ容量が必要になることを覚悟する 親リソースには、リビジョン機能を提供しないという選択肢もあり 言い換えると、子リソースを持たない独立しているリソースのみリビジョン機能を提供する メモ 基本的にリソースは、最新の状態のみ提供する。 しかし、状況によっては、過去の状態のリソースが必要になることもある。 本章では、リソースを、以前のリビジョンにロールバック可能にする手段を見ていく。 これまでのAPIでは、リソースの過去の状態は考慮しなかった。 過去のリソースの状態を扱うと、リソースの履歴を時系列で見ることが出来る。 これは、利用者にとってメリットになり得る。 概要 リソースの過去の状態を表現するために、「リソースリビジョン」という概念を利用する。 リソースリビジョン : 一意の識別子と作成時のタイムスタンプでラベル付けられた、リソースのスナップショット リソースリビジョンは、リソースに以下二つのフィールドを追加することで実現可能。 リビジョン識別子 スナップショットが取得されたときのタイムスタンプ 実装 リビジョン識別子 リビジョン識別子は、一般的な識別子と同じくランダムな文字列を使用する。 以下の選択肢はあまり考えられない。 連番 リビジョンを削除すると、1,2,4 のように歯抜けとなり、利用者に混乱を招く タイムスタンプ 稀に、タイムスタンプ（≒識別子）が衝突する可能性がある リビジョンを作成する リビジョンは、暗黙的に作成するか、明示的に作成するか、選択することが出来る。 リビジョンの生成方法は、API全体で一貫していることが重要。 暗黙的なリビジョン API側で、特定のイベントに合わせて、自動的にリビジョンを作成する戦略。 リソースのデータが更新されたとき cron のような定期実行 特定のマイルストーン 特定のフィールドが更新されたとき 特定のカスタムメソッドが実行されたとき など ビジネスの要求に応じて、リビジョンを作成する最適なタイミングを模索すること。 リビジョンは、減らす方向よりも増やす方向をお勧めする。 明示的なリビジョン リビジョンを作成できるカスタムメソッドを用意し、利用者が明示的に作成できるようにする戦略。 リビジョンの作成は、API利用者が制御できる（責務も負う）。 特定のリビジョンを取得する 標準の getメソッドを拡張して、過去のリビジョンを指定してリソースを取得する手段を提供する。 Messageリソースのリビジョン 1234 を指定する例 GET chatRooms/1/messages/2@1234 リビジョンを指定しない場合、レスポンスのIDフィールドにはリビジョン情報を含めない（ revisionIdフィールドに、リビジョン情報を含める）。 リビジョンを指定した場合、レスポンスのIDフィールドにはリビジョン情報を含める（ revisionIdフィールドに、リビジョン情報を含める）。 方針としては、リクエスト時に指定するIDと、レスポンスのIDを一致させること。 リビジョンのリストを取得する リソースのリビジョン一覧を返す、カスタムメソッドを提供する。 以前のリビジョンを復元する restoreRevision カスタムメソッドを使用して、リソースを、ある過去の状態に戻す。 指定されたリビジョンのリソースをコピーし、最新のリビジョンとして新規作成することで実現する。 この機能では、リソースの履歴を削除したり変更してはならない。 リビジョンを削除する 特定のリビジョンに、誤って機密データや機微な情報を含めてしまった場合に使用する。 リソースのリビジョンを削除する、カスタムメソッドを提供する。 この時、標準の delete メソッドを拡張する形で実装してはならない。 標準の delete メソッドはリソースの削除を目的としており、 リビジョンを削除する機能とは区別する必要がある 区別しないと、利用者が混乱する 削除は危険な操作のため、混乱をできるだけ避けたい 現在（≒最新）のリビジョンを削除する場合、412 エラー、またはそれに相当するエラーを返す。 これにより、一つしか存在しないリビジョンを削除するケースも同時に解決できる また、リビジョンに論理削除の仕組みを提供するべきではない。 子リソースを処理する 子リソースをもつリソース（つまり親リソース）のリビジョンを作成する場合、子リソースをどう扱うか。 正解はなく、ビジネス要件次第。 「子リソースごとまとめてリビジョンに含める」というビジネス要件があれば、子リソースごと扱うよう拡張することになる 処理が複雑化し、より多くのストレージが必要になるのは間違いない 親リソースはリビジョン機能の対象外として定義するのも有り トレードオフ リビジョン機能の提供と、APIの複雑化のトレードオフ。 特に、階層を考慮したストレージは、より複雑で、多くのストレージ容量を要する。 扱うこと リソースのリビジョンを、時間の経過とともに変更しながら安全に保存する方法 個々のリビジョンを識別する方法 暗黙的または明示的にリビジョンを作成する方法 利用可能なリビジョンをリストアップし、特定のリビジョンを取得する方法 前のリビジョンに戻す方法 リビジョン指定可能なリソースの子リソースをどうすべきか まとめ リソースのリビジョンは、リソースのスナップショットとして機能する リビジョンの識別子は、他のリソース同様ランダムな値を用いる タイムスタンプや数字が増えるだけの値を用いてはならない リビジョンは、暗黙的、あるいは明示的に作成できる 暗黙的の例 : リソースが変更されるたび 明示的な例 : 利用者からの要求に応じて リソースのリビジョンを指定する場合、@ の後ろにリビジョン識別子を指定するとよい　 例) GET /chatRooms/1234@5678 ただし、リビジョンのリスト機能と削除機能は、カスタムメソッドで提供する リソースは、カスタムメソッドを使用して、以下の手順で前のリビジョンに復元できる 前のリビジョンと同じリビジョンを作成 作成したリビジョンをアクティブリビジョンとしてマークする