メインコンテンツまでスキップ

Software Design 202404

テクニカルライティング

読み手に合わせて文章を書こう

まずは読み手の前提知識がどの程度あるかを把握する。エキスパート向けなのか初心者向けなのかなど。

つぎに読み手の目的を把握すること。読み手が何を知りたいのか、どのくらい詳細に求めているのかなど。

そのうえで、以下のような工夫をすると良い。

  • 用語を適切に選択する
    • 専門用語を使うか使わないかなど
  • 書くべき情報を絞ったり、ドキュメントを分解したりする
    • 読み手の前提知識や目的に合わせて、必要な場所だけ読めるようにする
  • 読み手の範囲を絞り込む
    • 範囲を絞ればコスパは上がる
    • 冒頭に「対象読者、説明すること、説明しないこと」を明記するとよい

アウトラインで伝える情報を整理しよう

アウトラインを作成する際は以下の手順で行う。

  • 伝えたい情報を書き出す
  • 書き出した情報を階層化する
  • 項目を並べ替える
    • 「重要度」or「ニーズの大きさ」の順に並べ、次に「既知から未知」or「時系列」で並べるとよい。
  • 見出しにする要素を選ぶ
    • すべてを見出しにする必要はなく、小さなものは段落ですませてもよい
  • 見出しに分かりやすい名前を付ける

明確な文章を書こう

効率良く読める文章を書くために

ドキュメントは飛ばし読みされるものと心得よ。例えば F パターンなど。

重要なことから書こう。重要とは、読み手に必ずやってほしいことや、書き手の主張である。

一文一義で書こう。長い文章は読みづらい。1 つの行動ごとに 1 つの文章にするとよい。

一文を短くしよう。余分な接続詞を削ったり、「まずはじめに」を「まず」にするなど。

読み手の視点の言葉で書こう。このとき、能動態(読み手の行動)と受動態(行動の結果)を適切に使い分けよう。例えば「PR の作成をトリガーとしてテストを実行します」ではなく「PR を作成するとテストが実行されます」のように。

主語と述語を対応させよう。主語と述語以外の部分を省いても意味が通じるかどうかを確認するとよい。

係り受けを明確にしよう。主語と述語を近づけたり、複数の修飾語がある場合は長いほうを前に持ってきたりすると改善する。

並列(not 順列)の情報が3つ以上ある場合には箇条書きにしよう。

読点を適切に打とう。意味の切れ目や誤解されそうなところに打つとよい。

誤解を招かない文章を書くために

できるだけ具体的に書こう。例えば「すぐに」という表現は曖昧なので、具体的な時間を書くなど。

肯定形で書こう。「残したままにしないでください」ではなく「消してください」とするなど。なお、否定形は禁止事項を伝える際に使うとよい。

二重否定を避けよう。それ、肯定形で書けますから。

「の」は一文に2つまで。それ以上になったら言い換えられないか考えよう。

段落の作り方

段落とは、同じ内容のまとまりごとに分けた一区切りのこと(日本人が小学校で習う段落は改行とイコールだが、ここで言う段落はそれとは異なる)。

段落を作るときは、はじめにトピックセンテンスを書く。これは段落の要約である。

つぎにサポートセンテンスを書く。これはトピックセンテンスを補足する内容、具体例、理由や根拠などである。

その後、話題を展開していく。この際「概要から詳細へ」を意識する。並列の情報は同じ表現を使って書く。順列の情報は「既知から未知へ」の流れで書く。

リソースレコード変更時のベストプラクティス

リソースレコードの設定変更は即時に反映されない場合がある。このため、TTL をあらかじめ 300 秒くらいに短くしておくのがよい。ただし、後で戻すのを忘れずに。通常は 3,600 秒くらいがよい。

もしトラブルシュートが必要になったら、dig を使って非再帰問い合わせをしたり、キャッシュ問題の切り分けのために別のネットワークや端末から確認してみたりするのが有効である。

ネガティブキャッシュ問題

サブドメインを新たに設定する際などに、設定前に(まだ存在しない)サブドメインにアクセスしたときに上位の権威サーバがNODOMAINを返すことで、その情報が TTL 期間キャッシュされてしまい、その間はサブドメインにアクセスできなくなる問題。非常に厄介な問題だが、dig での非再帰問い合わせや、別のキャッシュサーバを使って状況を確認するのが有効。

権威サーバ引っ越し時のベストプラクティス

権威サーバ(ドメイン管理サイトで登録している NS レコードのこと)を引っ越す場合には、TTL が効かない。このため、数日間は新旧どちらの権威 DNS にもリクエストが飛ぶことになる。スムーズな移行のためには以下の手順を踏むことが大事。

  • 新旧権威サーバでリソースレコードをあらかじめ同期しておく
  • 権威サーバ(e.g. Napecheap のコンソールで登録している NS レコードの内容)を書き換えて数日待つ
  • その後、もし A レコードの変更などがあわせて必要であれば前述の手順に沿って行う

Chrome

画面を描写する仕組みは、Content、レンダリングエンジン(Blink 本体)、サードパーティライブラリ(V8, Skia ほか)の3層からなる。

Content が提供する Content public API によって Chrome その他の各種ブラウザから利用できるようになっている。

プロセスには以下のようなものがある。

  • ブラウザプロセス
    • Web サイトの描写エリアの外側に責務を負う
    • 戻るボタンやブックマークの機能など
    • プロセスは 1 つ
  • レンダープロセス
    • Web サイトの描写を行う
    • タブごとに 1 つずつのプロセス
  • Viz プロセス
    • 前述の2つのプロセスを組み合わせて実際に画面を描写する
    • プロセスは 1 つ

開発者体験

腐った iOS アプリを再建した手順を紹介。

まずは UI テストの実装。Firebase Test Lab 上で UI テストを実装した。画面操作を行った後に、正しいリクエストが送信されるか検証するもの。

次にリアーキテクチャ。TCA という Redux 的なものを導入して状態変化を追いやすくした。

他にも Renovate によるライブラリの自動更新や、VRT の導入などを行った。

データベースリファクタリング

「キャッシュ中毒」というアンチパターンがある。サービスが強くキャッシュに依存してしまい、非常に壊れやすくなり、運用が難しくなる状態のこと。一方で過度な忌避もよくない。適切なバランスを保つことが重要。

まずは RDBMS の性能を使い切るのが先。ほとんどの問題はこれで解消される。具体的には、インデックスの活用、クエリの最適化、テーブルの正規化など。

キャッシュに適しているものは以下のとおり。

  • アクセス数が多い
  • 計算コストが高い
  • 更新頻度が少ない

また、データ更新のアルゴリズム、生存期間のアルゴリズムには様々な種類があるので、最適なものを選択すること。

AWS Systems Manager

AWS Systems Manager は、サーバの管理を行うためのサービス。Lanscope Cat + α みたいなやつで、情報収集、リモート操作、パッチの適用、メンテナンス処理などを行うことができる。他クラウドやオンプレのサーバ、IoT デバイスにも対応している。