Upgrade to Pro — share decks privately, control downloads, hide ads and more …

エンジニアのためのドキュメント力基礎講座

 エンジニアのためのドキュメント力基礎講座

エンジニアに向けたドキュメント作成能力向上のための社内研修用のコンテンツを一部加工して公開しました。(2020/5/14:ver1.1 公開しました)

■概要
設計書やテスト仕様書などシステム開発にドキュメントは欠かせません。品質の高いドキュメントを効率的に作成するためのコツと勘所をわかりやすく解説します。

■ターゲット
・ドキュメント作成作業に苦手意識や抵抗がある人
・資料がわかりにくいという指摘を受けたことがある人
・「構造化」と言われて実はあまりピンと来ていない人
・仕事の段取りをつけるのがあまり得意ではなない人

■期待効果
・読み手にわかりやすいドキュメントとは何かがわかる
・ドキュメントの作成アプローチがわかる
・ものごとに対する効率的な取り組み方がわかる
(できるようにするには継続的な鍛錬が必要)

中野康雄(ARI)

May 14, 2020
Tweet

More Decks by 中野康雄(ARI)

Other Decks in Technology

Transcript

  1. 自己紹介 twitter/note/Qiita で情報発信中。 良かったら覗いてみてください♥ 中野 康雄(なかのやすお) 兵庫県宝塚市出身 S49年生 ARアドバンストテクノロジ株式会社 取締役執行役員(事業担当)

    兼TechCoE事業室長  全社戦略、事業管理、PJ品質管理 人材育成、中途採用、一部PJ業務 などを担当  元流通経済大学 非常勤講師 (Eビジネス論)  PMP/情報処理安全確保支援士 AWS認定ソリューションアーキテクトアソシエイト JDLA G検定 2
  2. システム開発系ドキュメントの特徴 • 自分以外の誰かが読み、更新されることが前提とされる  レビュワー  後工程の担当者  保守担当者 •

    抜け漏れや、読み手によって解釈が異なることは許されない  検討すべきことの抜け漏れは手戻りにつながる  解釈が異なる記述をしてしまった場合も同様 • 納期があり生産性が求められる  書き手が納得いくまで時間をかけて良いわけではない  事前に作成工数の見積りが求められる 11
  3. システム開発系ドキュメントに求められること • 品質  誤字脱字、最低限の体裁、表記の統一  書くべき項目がすべて書かれている  内容が正確 •

    読み手にわかりやすいこと  全体構成、見出しの粒度、順序が適切  各文章がわかりやすい  体裁が適切に「デザイン」されていること(タイトル、表紙、インデント、ページ番号など) • 生産性や作業管理性が高いこと  標準化され一定のルールがある方が書きやすく、レビューもしやすい  作成にかかるタスクが分解できている(見積りの精度が上がる)  完了までの段取りが出来ている(アウトライン化) 12
  4. シ ス テ ム 開 発 の 時 間 軸

    システム開発の大きな流れ 要件 人間の 世界 システムの 世界 設計 実装(ソフトウェア/基盤) 要求 要望 仕様 要件 1.要望要求から要件に選別する 2.要件に対する仕様を記述する 3.仕様を満たすように設計する 4.設計通りに実装する 5.仕様&要件の実現を確認する 14
  5. シ ス テ ム 開 発 の 時 間 軸

    要件は仕様化されなければ実現できない 要件 人間の 世界 システムの 世界 氏名を表示できたらいいな その他多くの要望 各ページに氏名を表示できること 各ページのヘッダ部分に 「◦◦[半角スペース]••」と表示する。 ◦◦は姓、••は名を表す。 ユーザー内 整理 QCD制約踏まえた 要求精査 各ページに氏名を表示したい 網羅的かつ 誤解を与えない 言語化 仕様の網羅的かつ誤解なき言語化が システム開発の最初の勘所 設計 実装(コード) 要求 要望 仕様 要件 • あったらいいなだよね?目的は?本当に必要? • 個人の意見?みんなの意見? • 要求の優先順位は? • 予算や納期踏まえて今回どれやる? • ページのどこ? • どんな風に表示するの? 参考: https://qiita.com/digdagdag/items/2808205d89344ab8a3a1 イメージ 15
  6. 構造化されている例 資料間の関係  画面一覧と画面設計書  機能一覧と各機能設計書  システム構成一覧と構成別パ ラメータシート 

    移行全体スケジュールと各移行 作業詳細手順書  共通仕様書と各個別仕様書 各資料内の目次構成 例:要件定義書 1. システム導入の目的と目標 2. システムの概要/システムの構想 3. システム導入後の業務フロー 4. 機能要求 5. 入力要求と出力要求 6. 品質・性能要求 7. セキュリティ要求 重複を避ける 漏れ重複ない章立て (一般例) 22
  7. こういう問題昔やりましたよね? 問題:□に入るものを答えよ Q1:1, 2, 4, 8, □, 32, 64 Q2:J,

    F, M, A, M, □, J, A,・・・ 33 この問題の本質は、各Qの主題を探すことにいる
  8. 目次とはその資料の論点である 各資料内の目次構成 例:要件定義書 1. システム導入の目的と目標 2. システムの概要/システムの構想 3. システム導入後の業務フロー 4.

    機能要求 5. 入力要求と出力要求 6. 品質・性能要求 7. セキュリティ要求 漏れ重複ない章立て (一般例) 37 要件定義書の論点 つまり 何を書けば 要件が定義できたと 言えるのか?
  9. 構造化演習(2)ある事例 49 » コミュニケーションの方向に着目したふりかえりの方法 - よこなのへたのよこずき https://ihcomega.hatenadiary.com/entry/2020/04/28/055258 • KPTでやっていた •

    でも過去振り返りの時間が足りなくなることが頻発 • 議論しなくてもよいことは議論しなくてもいいのでは? • チーム(または個人) で続けたいこと • 自分 がドヤりたいこと • チームメンバー にお礼したいこと フレームワークを使うことがゴールにならないように 結果や得たい成果を常に忘れないようにしたい
  10. 今日のまとめ  ドキュメント作成に求められるスキル  漏れなく誤解なく言語化する  知識+作文能力+構造化思考  構造化思考とは? 

    「分かる」は「分ける」  分解+グルーピング(思考の補助線)  構造化思考の演習  いきなり手を付けず、何を考えるべきかを考える  ドキュメント作成の進め方  目的から逆算して段取りを考える 56
  11. エンジニアのキャリアを考える上で大切なこと 63 ハード スキル ソフト スキル エンジニア(プロフェッショナル)の 市場価値 ハードスキル 体系だった知識や技術

    定量化や表現が比較的しやすい ソフトスキル  ヒューマンスキル  定量化や表現も比較的難しい 経験値  判断や設計センスに場数は必要  経験を再現性あるスキルに 変える力も重要 経験値 参考:https://www.slideshare.net/hiroyukitakah/ss-62940166 →自己研鑽がこちらに偏りがち →後回しにしがち
  12. 武器は最新/最適で多いに越したことはない 64 □PHP、□Java、□SQL、□ASP.NET、□PL/SQL、 □Perl、□C#、□Object-C、□Swift、□C言語、 □COBOL、□C++、□COBOL、□Excel、□VBA、 □VB、□SQL Server、□Ruby、 □Ruby On Rails

    、 □VB.NET、 □Oracle、□C#.NET、□Access VBA、 □ASP、□iOS、 □Android、□Windows、 □Linux、 □UNIX、□CSS、 □JavaScript、 □Flash、□HTML、 □Photoshop、□Illustrator、 □ AutoCAD、□Cisco、 □VMware、□Azure、 □AWS、□Docker、□Redmine、 □Git、 □GitHub、□PMBOK ハード スキル ソフト スキル エンジニア(プロフェッショナル)の 市場価値 経験値 ・・・・・
  13. ハードスキルを成果に変えるにはソフトスキルが大切 65 ハード スキル ソフト スキル エンジニア(プロフェッショナル)の 市場価値 カテゴリ 項目

    コミュニケーティング コミュニケーション ネゴシエーション リーディング ビジョニング チーム活性力(他者への影響、笑力) 率先垂範 動機づけ マネージング 計画性 モニタリング(目標達成型進捗管理) エフェクティブネス(効果性) コンフリクトマネジメント 関係調整力 判断力 認知力 全体的(戦略的)視点 情報収集 問題発見力 課題解決力 プロフェッショナリズム (プロ意識・自己規律) 責任感(達成志向) 倫理観・誠実性 多様性の尊重 引用:PM育成ハンドブック/ IPA(独立行政法人情報処理推進機構)発行 経験値