海外との多拠点開発の話 - 社内文書アンチパターン

- [海外との多拠点開発の話 - 東京で開発のための通翻訳チームを立ち上げたことを振り返る - Qiita](https://qiita.com/e99h2121/items/24f7beb0ee847332331e)
- [海外との多拠点開発の話 - 開発のための通翻訳チームの挑戦を振り返る - Qiita](https://qiita.com/e99h2121/items/00374d4bd27ec09b27e6)

具体的に直面した困難を書いてみます。文はアンチパターンと、こうだったら良かった例。


## 文書のアンチパターン

### アンチパターン例1
```例文.md
解析ツールでバグを減らそうとしている件について。
※解析ツールとは：
静的/動的コンパイルどちらも対応していて、バグを検知して一覧を出す機能
```
#### 改善案
一見良さそうなどこにでもある文だが、「の件について」が現れたら考えたい。
**このパートで何が話し合われたか、それは「共有」なのか「提案」なのか「検討」なのかを明確にする。** そのため、「の件について」という表現ではなく、"「」" 等をつけて表題とする。オリジナルでは解析ツールを使おうとしている件、という表題だが、実際にはそれをふまえてチームでも使おうという「提案と検討をしている」ので、その内容を的確に要約した表題にすべき。注釈などの文章は”( )”などでかこんで別の種類の文章であることを明確にするのも大事。

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


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

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

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

```案.md

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


### アンチパターン例3

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

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


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

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

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

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

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

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

```

### アンチパターン例5

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

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

```案.md
21:プロジェクト
（田中）
- V2系ユーザーで2つの問題が発生中。

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

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


### アンチパターン例6

```例文.md
（山下）
お客様で監査ログちゃんと使ってるが、でなくなる事はないか
（中田）
全処理ででなくなる事はない。
（大田）
社内環境は監査ログの設定がオフになっているがつける場合は相談して欲しい。
（中田）
今回のnullチェックを入れないとそもそも今画面でErrorになっているはず。
NullPointerExceptionが発生する場合だけログが出ないがそもそも出てないはずなので、
影響はない。
``` 
#### 改善案
**同一人物の発言ならまとめるだけでも読みやすくなる。**
上の例では中田さん。発言を逐一その順番通りに書かなくて良い。

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


### アンチパターン例7

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

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

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


## 以上が「失敗」

**「意図を正しく伝えたいから日本語で」話しますと、みな言う。
しかしその伝えたいは単に自分が「喋りたい」であり「あなたに正しく受取ってほしいから」とは違う。**

ルールって、何のためにや人の顔そのものが見えないと闇を感じがちですね。
議事録だけでなくドキュメントには執筆者の名前と問い合わせ先をいれてほしい。顔を想像したい。

結局この通翻訳チームプロジェクト、私の2人目の産休のタイミングで役割としては終了。
「文書翻訳依頼受付終了のお知らせ」を発表したことがむしろ区切りとしては成果である。笑


> - **プロジェクト稼働状況**
    - インフラとして稼働させた内容の報告
    - 各種ナレッジ等蓄積場所の報告
    - 直近で投下されていた費用
        - 既に、翻訳は蓄積された社内辞書や機械翻訳、有志活動、自己研鑽等により、ある程度の品質が確保できる。この翻訳は自ら有志単位で既に業務を十分こなせているチームと、そうでなく翻訳依頼に依存したチームとの公平性を模索したい。
通訳は社内の口述技術に依然課題がある。
- **今後のアクション**
    - 「翻訳」依頼受付を終了し通訳中心にする。
    - 有志単位で解決しているチームのノウハウをそうでないチームに展開する。
    - 自己研鑽を継続して支援する。
`

話はひと区切り。今後の野望に続きます。
以上です～。