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

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

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

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

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

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

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

pixta_37443582_S

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

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

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

bar9

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

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

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

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

bar_sankaku_blue

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

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

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

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

2020-08-12 06:00:46

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

2020-08-11 06:00:34

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

2020-07-20 06:00:23

システムエンジニアがやりがいを感じる瞬間 【先輩や仲間との交流】

2020-07-13 06:00:17

システムエンジニアがやりがいを感じる瞬間【自分の製品を発見】

2020-07-10 06:00:05

システムエンジニアがやりがいを感じる瞬間【誰かの役にたったとき】

2020-07-09 06:00:22

今年もやります!プログラミング体験「ソルクシーズのインターンシップ」みんなの体験談【後編】

2020-07-07 06:00:42

今年もやります!プログラミング体験「ソルクシーズのインターンシップ」みんなの体験談【前編】

2020-07-06 06:00:54

キャリア推進本部・発足記念企画第2弾「やりたいことを本部長にいってみよう!」②

2020-06-18 06:00:36

キャリア推進本部・発足記念企画第2弾「やりたいことを本部長にいってみよう!」①

2020-06-17 06:00:32

ソルクシーズ人事の挑戦!「Web面接&説明会システムを使ってみた」②

2020-06-09 06:00:01

ソルクシーズ人事の挑戦!「Web面接&説明会システムを使ってみた」①

2020-06-08 06:00:13

毎日、発見!? 総力特集・ソルクシーズのテレワークレポート【業務の変化編】

2020-06-03 06:00:35

毎日、発見!? 総力特集・ソルクシーズのテレワークレポート【コミュニケーション編】

2020-06-02 06:00:23

毎日、発見!? 総力特集・ソルクシーズのテレワークレポート【生活の変化編】

2020-06-01 06:00:27

2020年【春】の新入社員からの『アンサーメッセージ』【2】

2020-05-21 06:01:37

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

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

2020-08-12 06:00:46

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

2020-08-11 06:00:34

私の評価はどうなるの?テレワークで変わる人事評価「笑える話」「情けない話」

2020-08-06 06:20:08

私の評価はどうなるの?テレワークで変わる人事評価「楽しみな話」「前向きな話」

2020-08-05 06:00:25

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

2020-07-20 06:00:23

令和に求められる「IT人材」のプロフィール③チャレンジ人材

2020-07-15 06:00:18

システムエンジニアがやりがいを感じる瞬間 【先輩や仲間との交流】

2020-07-13 06:00:17

システムエンジニアがやりがいを感じる瞬間【自分の製品を発見】

2020-07-10 06:00:05

システムエンジニアがやりがいを感じる瞬間【誰かの役にたったとき】

2020-07-09 06:00:22

今年もやります!プログラミング体験「ソルクシーズのインターンシップ」みんなの体験談【後編】

2020-07-07 06:00:42

今年もやります!プログラミング体験「ソルクシーズのインターンシップ」みんなの体験談【前編】

2020-07-06 06:00:54

キャリア推進本部・発足記念企画第2弾「やりたいことを本部長にいってみよう!」②

2020-06-18 06:00:36

キャリア推進本部・発足記念企画第2弾「やりたいことを本部長にいってみよう!」①

2020-06-17 06:00:32

令和に求められる「IT人材」のプロフィール②満足度向上人材

2020-06-15 06:00:40

令和に求められる「IT人材」のプロフィール①最先端人材

2020-06-10 06:00:38

ソルクシーズ人事の挑戦!「Web面接&説明会システムを使ってみた」②

2020-06-09 06:00:01
ページTOPへ