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

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

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

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

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

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

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

pixta_37443582_S

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

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

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

bar9

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

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

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

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

bar_sankaku_blue

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

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

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

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

2020-10-16 10:38:07

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

2020-10-16 10:35:01

転職してわかったこと~5人のリーダーの本音③行き詰まりからの脱却

2020-10-08 06:00:50

転職してわかったこと~5人のリーダーの本音②人柄に惹かれて入社を決意

2020-10-06 06:00:08

転職してわかったこと~5人のリーダーの本音①キャリアの選択肢を広げたかった

2020-10-02 06:00:04

社内研修もオンラインセミナーへ!?「ソルクシーズアカデミーの野望」

2020-09-23 06:00:54

アフターコロナとソルクシーズ④ イー・アイ・ソルの未来予知

2020-09-14 09:00:04

アフターコロナとソルクシーズ③ いまイルモの未来

2020-09-11 06:00:00

アフターコロナとソルクシーズ② エクスモーションの挑戦

2020-09-09 06:00:07

アフターコロナとソルクシーズ① Fleekdriveを取り巻く環境

2020-09-07 06:00:56

テレワーク大好き派・つらい派、それぞれの言い分

2020-09-03 06:00:41

人事・研修担当者たちが語る「初めてのオンライン研修奮闘記」

2020-09-02 06:00:53

ソルクシーズが第2新卒を歓迎する理由!

2020-08-26 06:00:07

コロナ時代の新人研修 どっちがよかった?リモート研修と集合研修

2020-08-12 06:00:46

コロナ時代の新人研修…いかがでした?受講者側から結果発表!

2020-08-11 06:00:34

テレワークで注目度UP!「ビジネスチャット」活用 現場の声

2020-07-20 06:00:23

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

5分でわかるITトレンド2020 5)自動運転

2020-10-26 06:00:45

5分でわかるITトレンド2020 4)スーパーアプリ

2020-10-23 06:00:38

5分でわかるITトレンド2020 3)DARQって何?

2020-10-21 06:00:52

5分でわかるITトレンド2020 (2)〇〇現実編

2020-10-19 06:00:23

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

2020-10-16 10:38:07

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

2020-10-16 10:35:01

転職してわかったこと~5人のリーダーの本音③行き詰まりからの脱却

2020-10-08 06:00:50

転職してわかったこと~5人のリーダーの本音②人柄に惹かれて入社を決意

2020-10-06 06:00:08

転職してわかったこと~5人のリーダーの本音①キャリアの選択肢を広げたかった

2020-10-02 06:00:04

社内研修もオンラインセミナーへ!?「ソルクシーズアカデミーの野望」

2020-09-23 06:00:54

アフターコロナとソルクシーズ④ イー・アイ・ソルの未来予知

2020-09-14 09:00:04

アフターコロナとソルクシーズ③ いまイルモの未来

2020-09-11 06:00:00

アフターコロナとソルクシーズ② エクスモーションの挑戦

2020-09-09 06:00:07

アフターコロナとソルクシーズ① Fleekdriveを取り巻く環境

2020-09-07 06:00:56

テレワーク大好き派・つらい派、それぞれの言い分

2020-09-03 06:00:41

人事・研修担当者たちが語る「初めてのオンライン研修奮闘記」

2020-09-02 06:00:53
ページTOPへ