template

概要

テンプレートはコミュニケーションや思考の枠組みとなる。さらに改良して次に活かすことができる。

利点。

  • ソフトウェア開発では正確なコミュニケーションが重要になる。
    • 抽象的で理解しづらいから。伝わっているかわからないから。
  • 文字でのやりとりでは、キャッチボールなく一度に伝える論理性の強さが必要。テンプレートは効果的に使える。
  • 沿って書くことでスピードも上がる。
  • テンプレートに慣れることで、ほかの似たようなことにも応用できる。

Commit Messages

David Winterbottom

A useful template for commit messages — David Winterbottomを日本語にした。 

# 適用された場合、このコミットは…

# なぜこの変更が必要か?
この変更の前は、

# この問題をどう解決するか？
この変更は、

# 関連チケット、リンク、記事などの情報源を入力

Conventional Commits

  • Conventional Commits
    • コミットメッセージのための規約であり、テンプレートとは違うが参考になる。

Design doc

Design docはプロジェクトへ取り組む前に書く仕様書。 これを元に人や資源を集め、期間を設定し…メンバーのプロジェクトへの理解を深める、というふうに基盤となっていく。

有名企業がテンプレート公開してたりする。

Googleのデザインドック

Googleのデザインドックのマークダウンサンプルらしいから持ってきた。

Game Design Doc

Design Document - Roguelike Tutorial - In Rust

  • Characters
  • Story
  • Story Progression
  • Gameplay
  • Goals
  • User Skills
  • Items and Power-Ups
  • Progression and challenge
  • Losing
  • Art Style
  • Music and Sound
  • Technical Description
  • Marketing and Funding
  • Localization

RFC

RFCはインターネットで用いられるさまざまな技術の標準化や運用に関する事項など幅広く情報共有するために公開される文書シリーズ。仕様決定の参考になる。

RFC 2223 - Instructions to RFC AuthorsではRFCフォーマットを規定している。

  • 概論
    • 背景
    • 目的
    • 方法
    • 結果
    • 結論
  • 文書のステータス
  • 目次
  • 序論
    • 導入
  • 慣用と定義
    • 用語
  • 内容
  • リファレンス

カスタマーサービス

メールを送る前に試してほしいこと、よくある問題をまとめておく。実際にメールを送るときもフリーテンプレートでなく調査結果や、試したことを項目として入れておくことで価値のある情報になる。

テンプレートがない場合、「動きません」みたいなメールが来て何のヒントにもならない。再度基本的な情報(ブラウザ、ネットにつながってますか…)を聞くが時間がかかる。エンジニリング的に何もヒントになる情報がないのにユーザは怒り始め、サービス担当者から急かされることになる。

AmazonやGoogleなど、莫大なサポートをしている企業のページはかなり参考になる。たいていの問題はサポートへ問い合わせる前に解決する。もし解決しなくても少しでも早く解決するための方法が整備されている。

DB Design

DB設計の共有をするためのテンプレート。技術的フィードバックをもらうためには、背景を完全に共有する必要がある。共有せずに最高の答えをもらうことは期待できない。

背景

  • 既存の機能の説明
  • 用語やテーブルの解説

やりたいこと

  • やりたいこと。
  • なぜそれをやる必要があるか
  • どのような利点があるか
  • モック。イメージ
  • ユーザのユースケースの例。どのように遷移してその機能を使用するか

制約と解決策

  • どのような難しさがあるか
  • 解決方法

ER図と説明

  • ER図の意図の説明

SQL制約

  • PRIMARY KEY
  • FOREIGN KEY (ON DELETE, ON UPDATE…)
  • NOT NULL
  • UNIQUE KEY

運用

  • データの初期セットはどうやって誰が行うか
  • データが途中で変わる可能性はあるか
  • いつ追加されるか
  • 誰が編集するか

エッジケース

ビジネスサイドはごくわずかなケースしか考慮してない可能性が高い。 できるだけエンジニアサイドで事前に想定されるケースを出しておく必要がある。

  • Xの場合の表示はどうなるか

マージとリリースをどの段階で行うか

  • たとえばテーブルを切り替えるとDBだけの話しでなくなり、viewも切り替える必要があるわけだがそこはどうするのか。
  • どこまでユーザの影響があるのか。
  • どうやってできるだけ影響を少なくするのか。
  • 新機能はどの時点で見られるようにするのか。
  • リリースとはどういうことをいうのか、認識は合っているか(マスターブランチにマージすることなのか、デプロイすることなのか、ユーザが見られるようにすることなのか)。
  • 毎回デプロイもするが、ユーザには見えなくするのでよいか、あるいは専用にブランチを切って作業をするか。

データ移行はどうするか

(既存テーブルがある場合) 既存データをどうやって移行するか、どのタイミングで移行するか。 早すぎると反映しないので、基本的にコードの切り替えと同時になる。

sandbox環境はどうするか

現在の開発状況を随時反映すると、普段の業務でsandbox環境が使えなくなる。元からブランチごとで環境を用意するような開発環境だと問題ないが、開発体制によっては共用のテスト環境を用意している場合があるのでその確認をする。

ブランチ運用

随時マスターブランチにマージするのか、featureブランチにマージしていくのか。

作業の進め方

  • どの時点まで並列して進められるか
  • 破壊的変更はどこで起こるか
  • データの移行はどのタイミングで行うか

担当者

  • 誰が何を担当するか

Todo

  • 次までにやることはなにか

Briefing

参考: 【1時間で分かる】P&G流マーケティングの教科書｜石井賢介（Marketing Demo代表取締役）｜note マーケティング戦略を元に、広告代理店に依頼をするためのテンプレート。 広告代理店は戦略を作品に翻訳するのであって、戦略が存在して、うまく伝達しないことには機能しない。

作業手順書

  • 準備手順書: 移行作業当日までの準備のTODO
  • 停止手順書: AWSの旧システムを停止する手順書
  • 転送手順書: MySQLやオブジェクトストレージのデータを転送する手順書
  • 起動手順書: GCPの新システムを起動する手順書
  • 起動後手順書: 新システムが起動したあと、周辺システムなどを新システムへ切替える手順書
  • ロールバック手順書: 作業途中で問題が発生したときにAWSの旧システムを復旧させる手順書

よくしらんRailsアプリとかをAWSのレガシーシステムからGCPのイケイケシステムに移行した話 - nownab.logの例。

Memo

Tasks

Reference

Archives