🍎

開発者のための議事録リファクタリング - 例文と解答案 [revision.2]

5 min read

すべて例題。人名はすべて仮名です。
議事録となった例文を、どうしたら読みやすくできるか考えてみましょう。

具体例

例文1

解析ツールでバグを減らそうとしている件について。
※解析ツールとは:
静的/動的コンパイルどちらも対応していて、バグを検知して一覧を出す機能

解答案

一見良さそうなどこにでもある文だが、「の件について」が現れたら考えよう。
このパートで何が話し合われたか、それは「共有」なのか「提案」なのか「検討」なのかを明確にする。 そのため、「の件について」という表現ではなく、"「」" 等をつけて表題とする。オリジナルでは解析ツールを使おうとしている件、という表題だが、実際にはそれをふまえてチームでも使おうという「提案と検討をしている」ので、その内容を的確に要約した表題にすべき。注釈などの文章は”( )”などでかこんで別の種類の文章であることを明確にするのも大事。

「デバッグに解析ツールを使うことの提案と検討」について。
(※解析ツールとは:静的/動的コンパイルどちらも対応していて、バグを検知して一覧を出すツール)

例文2

山田さんのチームで解析ツールのGIT連携をしている。
プロダクトでとてもバグが多くて、コンパイル対策で解析ツールを導入したそう。
最初は東京だけでやっていたが、今では全拠点を巻き込みやっている。
最初は1~2万件のバグが検知されていたが、Gitと連携して減らすということをやっている。

解答案

プレゼンなどと同様、発言者の発言には必ず「背景」「結論(言いたいこと)」「細かい説明と理由」が存在する。 それを明確にする。3行以上の文章が表題もなく連なるとすでに議事録ではなくなる。中点や番号などを頻繁に使い、列挙。内容を箇条書きにしたり、簡潔な文章で表現する。

細かいが GIT なのか Git なのか揺れないようにしたい。


[背景]
- 山田さんのチームでは解析ツールのGit連携中。
- バグ過多に対するコンパイル対策で解析ツールを導入した。
- 最初は東京だけでの実施に始まり、今では全拠点を巻き込み実施中。
- 最初は1~2万件のバグが検知されていたが、Gitと連携して減らす。

例文3

目的は2つ。
GitへのソースPush時に解析ツールでバグを検知した場合はPushされないようにする。直さなければPushができない。マージリクエストの部分でも同じことをしている。結果を画面でもWebサービスでも見れるので承認者と開発者の教育観点になる。
これらにより品質向上を進めている。
製品テストフェーズにおけるバグ数・不具合の数の削減につながったとのこと。

解答案

「目的は2つ」と宣言しているなら、箇条書き。 整理するための記号を番号にするとよりわかりやすい。Markdown記法を用いると文を整理しやすい。

目的は2つ。
1. GitへのソースPush時に解析ツールでバグを検知した場合はPushされないようにする。直さなければPushができない。マージリクエストの部分でも同じことをしている。
2. 結果を画面でもWebサービスでも見れるので承認者と開発者の教育観点になる。これらにより品質向上を進めている。製品テストフェーズにおけるバグ数・不具合の数の削減につながったとのこと。

例文4

チームにおいても、私としては、追加費用が出せない事情もあるため
静的セキュリティスキャンの目的で解析ツールの導入を検討している。
品質にも同時に効果がありそうなので鈴木さんにやってもらいたい。プロダクトの機構を利用してやりたい。

(田中)
以前佐藤さんが解析ツールを使って調査した際に、数千単位のバグが検知されたと
記憶している。
それを0にすることはかなり工数がかかってしまう。
既存ソースは一旦対象外とし、今回直した差分などに絞って対象としていく形になると思う。

解答案

同様、「提案と検討」であることを明確にし、箇条書きで簡潔に表現する。箇条書きにした際、文の前後関係も整理して良い。
「私としては」等、その場限りの口語表現は不要。その代わり発言者を明記する。

また後半は、発言を受けた 意見であることを明記する。
発言には必ずポイントがあるため、それぞれのポイントごとに内容をまとめて分割して記録する。

[提案と検討]
(鈴木)
- チームにおいても、静的セキュリティスキャンの目的で解析ツールの導入を検討している。
- 追加費用が出せない事情もあるため。
- 品質にも同時に効果がありそうなので鈴木さんにやってもらいたい。プロダクトの機構を利用してやりたい。

[意見]
(田中)
- 以前佐藤さんが解析ツールを使って調査した際に、数千単位のバグが検知されたと記憶している。それを0にすることはかなり工数がかかってしまう。
- 既存ソースは一旦対象外とし、今回直した差分などに絞って対象としていく形になると思う。

例文5

21:プロジェクト
(田中)
・V2系ユーザーで2つの問題が発生してる。
 1つは、証明書がない問題。これは手順を共有しているので対象ユーザーには
 適用のタイミングで証明書の追加をしてもらう。もう1つは、お客様社内環境で通信ができない。
 ミドルウェアのバージョンが他のユーザーと違う事が原因の可能性があり、FickPackを充てないと
 いけないユーザーが出てくる可能性あり。ここについては高橋さんに協力してもらい問題の
 切り分けを行っているところ。
・開発の中で、監査ログ処理でエラーが発生している。
 監査ログ処理側に不具合があるので、一旦nullチェックだけいれて解決する。
 本流にも入れる必要があるが、全体に影響がある為一旦出荷する。

解答案

この項目はすべて田中さんの発言項目。
なので、田中さんの名前をトップに、インデントも他と明確に区別して書く。ここでも列挙のパターン。「してる」等、気づかないうちに書いてしまっている口語表現、「ユーザー」「お客様」等が揺れる点や、誤記はlint等で修正したい。

21:プロジェクト
(田中)
- V2系ユーザーで2つの問題が発生中。

1. 対象サーバの証明書がない。
対策:対象ユーザーには適用のタイミングで証明書の追加をしてもらう。中田さんに手順を共有済。
2. ユーザー社内環境で通信ができない。
原因:ミドルウェアのバージョンが他のユーザーと違う事が原因の可能性。
対策:FixPackを充てないといけないユーザーが出る可能性あるため、高橋さんの協力のもと問題の切り分け中。

- 開発の中で、監査ログ処理でエラーが発生している。
    - 監査ログ処理側に不具合があるので、一旦nullチェックだけいれて解決する。
    - 本流にも入れる必要があるが、全体に影響がある為一旦出荷する。

例文6

(山下)
お客様で監査ログちゃんと使ってるが、でなくなる事はないか
(中田)
全処理ででなくなる事はない。
(大田)
社内環境は監査ログの設定がオフになっているがつける場合は相談して欲しい。
(中田)
今回のnullチェックを入れないとそもそも今画面でErrorになっているはず。
NullPointerExceptionが発生する場合だけログが出ないがそもそも出てないはずなので、
影響はない。

解答案

同一人物の発言ならまとめるだけでも読みやすくなる。
上の例では中田さん。発言を逐一その順番通りに書かなくて良い。

(山下)
お客様で監査ログちゃんと使ってるが、でなくなる事はないか
(中田)
全処理ででなくなる事はない。
今回のnullチェックを入れないとそもそも今画面でErrorになっているはず。
NullPointerExceptionが発生する場合だけログが出ないがそもそも出てないはずなので影響はない。
(大田)
社内環境は監査ログの設定がオフになっているがつける場合は相談して欲しい。

例文7

(町田)
・適用依頼についてだがリーダーに状況把握してもらいなるべく適用者の負担を減らすようにする。
・全体的に開発が遅れているところには町田・村田がヘルプで入る予定でいる。
・代理注文について
各代行会社のシステム部門が工数が足りない状態。
理由は大きいユーザーから今回の開発で結構要望を言われているらしくその開発で
手いっぱい。その影響を受けてかは不明だが、代理注文時に利用する端末が1法人につき
2台しかもらえないらしい。また最短でも準備が3月末となる。申込書ももらえていないユーザーも
いるらしいので、お客様に端末準備を早めに動いてもらうようコンサルタント側でお客様に連絡してほしい。
そもそも代理注文のシステム仕様すら確定版が出てこない状況。

解答案

「代理注文について」と表題を区切ったのはいいが、内容がまとまっていない。
「要望」と「現状」とを明確に区別する。現状を箇条書きにする。

(町田)
1. 適用依頼は、リーダーに状況把握してもらいなるべく適用者の負担を減らすようにする。
2. 全体的に開発が遅れているところには町田・村田がヘルプで入る予定。
3. 代理注文について
[要望] ユーザーに端末準備を早めに動いてもらうようコンサルタント側でユーザーに連絡してほしい。
[現状]
- 各代行会社のシステム部門が工数が足りない状態。
- 理由は、大きなユーザーから今回の開発で要望を言われ、手いっぱいなため。
- その影響か、代理注文時に利用する端末が1法人につき2台しかもらえない。
- 最短でも準備が3月末となる。申込書ももらえていないユーザーもいるらしい。ユーザーAに関してはそもそも代理注文のシステム仕様すら確定版が出てこない状況。

参考

箇条書きを意識するにはMarkdown

すべての社内文書はMarkdownで書けばいいと思うこれだけの理由

表記ゆれにTextlint

textlint と VS Code で始める文章校正

練習問題

手を動かして学ぶ文章作成の技術[第1回:列挙の記述パターン]
手を動かして学ぶ文章作成の技術[第2回:具体例の記述パターン]
手を動かして学ぶ文章作成の技術[第3回:比較の記述パターン]

Discussion

ログインするとコメントできます