SE必見!IT現場で求められる「ドキュメンテーション」スキル

システム開発の基本設計書、要件定義書、テスト仕様書…。プログラミングは苦にしないけど、ドキュメント作成は気が重いというシステムエンジニアは少なくないようです。

「正しく動くシステムを作るよりも、人間に正しく理解させる方が100倍難しい」といわれると、つい同意したくなっちゃいますが、来週までに作らなければいけない資料があるという現実は変わりません。

テレワークが当たり前になりつつある昨今、ドキュメンテーションの重要度は今まで以上に高まっています。

今回は、ソルクシーズの社員に「ドキュメントを仕上げる際に心がけていること」をヒアリング。苦手意識があるエンジニアのみなさんの参考になればと考える次第であります。

7人のエンジニアが声を揃えるのは、「誰に何をしてもらうためのドキュメントなのかを明確にすること」「誰が読んでもわかるように記載すること」です。

目的が明確になれば、ドキュメントの構成にムダがなくなり、ターゲットにとってわかりやすい言葉や表現を選ぶことができます。ソルクシーズ社員が心がけていることを、いくつか紹介しましょう。

pixta_37443582_S

テスト仕様書の内容が曖昧だったばかりに、テストをやり直したことがあります。誰が読んでも同じように理解してもらうために、『長文を避け、簡潔に書く』『箇条書きの粒度を揃える』『客観的に記述する』といったことを意識しています

わかりやすく、簡潔に。何をすればいいのか、どういう結果が出ればいいのか、必要なことだけ記載しています。他のドキュメントとの関連についても添えておいたほうがいいですね

手順書は、誰が作業しても同じプロセスになるのが基本です。作業をアクションごとに分割し、必要があればスクリーンショット等を使って、曖昧さを排除しています

bar9

内容のわかりやすさと同様に、重要なのは「ストーリー・流れ」です。

資料には目次を付け、「全体から詳細へ」という順に構成すること。読み手の理解を促進するために「手順に沿って」「過去~現在~未来」「基本的な説明の後、応用編やハイレベルな内容に言及する」といった流れも意識したほうがいいでしょう。

パワーポイントなどで作成する説明書、設計書などにおいては、「ひとつのスライドに複数の話を盛り込まない」「あの、そのなどの指示代名詞を極力使わない」「使用する単語は統一し、ひとつのことを示すのに複数の単語を用いないようにする」ことにも気をつけたいですね。

構成面では「前のページに戻って確認しなければならない構成にしない」「説明のパートと参考データのパートを分けて、いいたいことがシンプルに伝わるようにする」といった工夫も効果的です。

bar_sankaku_blue

いかがでしょうか。なかなか奥が深いドキュメンテーションの世界ですが、ここに書かれていることを徹底するだけでも、読み手にとってわかりやすい資料を作れるようになるはずです。

それではみなさん、締め切りまでに資料提出をよろしくお願いいたします。

ソルクシーズで働く人々 と同一カテゴリの記事

1月に変わります!菜緒さんリニューアル日記!【コンテンツ企画編】

2020-12-25 06:00:34

1月に変わります!菜緒さんリニューアル日記!【コンセプト設計編】

2020-12-24 06:00:27

今年も挑戦!「IoTイノベーションチャレンジ2020」ソルクシーズチームの奮闘記【後編】

2020-12-16 06:00:27

今年も挑戦!「IoTイノベーションチャレンジ2020」ソルクシーズチームの奮闘記【前編】

2020-12-15 06:00:26

ソルクシーズグループ・激動の2020年を振り返る3 イー・アイ・ソル

2020-12-09 06:00:37

ソルクシーズグループ・激動の2020年を振り返る2 インフィニットコンサルティング

2020-12-08 06:00:17

ソルクシーズグループ・激動の2020年を振り返る1 エフ・エフ・ソル

2020-12-07 06:00:00

就活前に必修!ソルクシーズの1day仕事体験・参加者の生声レポート【後編】

2020-11-26 06:00:35

就活前に必修!ソルクシーズの1day仕事体験・参加者の生声レポート【前編】

2020-11-25 06:00:41

ソルクシーズの部活2020総括!「今年できなかったこと、来年やりたいこと」【後編】

2020-11-20 06:00:05

ソルクシーズの部活2020総括!「今年できなかったこと、来年やりたいこと」【前編】

2020-11-19 06:00:12

数字で見る働くソルクシーズ

2020-11-05 06:01:17

数字で見る優しいソルクシーズ

2020-11-05 06:00:28

数字で見る謙虚なソルクシーズ

2020-11-04 06:00:43

転職してわかったこと~5人のリーダーの本音⑤東京で働いてみたかった

2020-10-16 10:38:07

転職してわかったこと~5人のリーダーの本音④前職で一緒に働いたあの会社へ

2020-10-16 10:35:01

気になるテーマから 発想力UP と同一カテゴリの記事

1月に変わります!菜緒さんリニューアル日記!【コンテンツ企画編】

2020-12-25 06:00:34

1月に変わります!菜緒さんリニューアル日記!【コンセプト設計編】

2020-12-24 06:00:27

今年も挑戦!「IoTイノベーションチャレンジ2020」ソルクシーズチームの奮闘記【後編】

2020-12-16 06:00:27

今年も挑戦!「IoTイノベーションチャレンジ2020」ソルクシーズチームの奮闘記【前編】

2020-12-15 06:00:26

「IoTイノベーションチャレンジ2020(決勝大会)」(2020/11/20)

2020-12-11 06:00:21

ソルクシーズグループ・激動の2020年を振り返る3 イー・アイ・ソル

2020-12-09 06:00:37

ソルクシーズグループ・激動の2020年を振り返る2 インフィニットコンサルティング

2020-12-08 06:00:17

ソルクシーズグループ・激動の2020年を振り返る1 エフ・エフ・ソル

2020-12-07 06:00:00

就活前に必修!ソルクシーズの1day仕事体験・参加者の生声レポート【後編】

2020-11-26 06:00:35

就活前に必修!ソルクシーズの1day仕事体験・参加者の生声レポート【前編】

2020-11-25 06:00:41

ソルクシーズの部活2020総括!「今年できなかったこと、来年やりたいこと」【後編】

2020-11-20 06:00:05

ソルクシーズの部活2020総括!「今年できなかったこと、来年やりたいこと」【前編】

2020-11-19 06:00:12

ガートナーが発表!「2021年のITトレンド大予想」【後編】

2020-11-18 06:00:23

ガートナーが発表!「2021年のITトレンド大予想」【前編】

2020-11-17 06:00:58

あなたのやりとり大丈夫?オンラインコミュニケーション改善委員会

2020-11-16 09:00:18

数字で見る働くソルクシーズ

2020-11-05 06:01:17
ページTOPへ