Skip to content

Latest commit

 

History

History
459 lines (277 loc) · 13.5 KB

ドキュメント.md

File metadata and controls

459 lines (277 loc) · 13.5 KB

ドキュメント

ドキュメントの種類

  • 方針/マニュアル
  • 規定類
  • 手順書/フロー
  • 記録類

記録類

  • 仕様書

仕様（しよう、英: Specification）とは、材料・製品・サービスが明確に満たさなければならない要求事項の集まりである[1]。仕様を記述した文書を仕様書と呼ぶ

  1. 要求仕様書（要件定義）
  2. 機能仕様書
  3. テスト仕様書
  • 設計書

具体的にどう作ったかをの記録を残す

書き方

テクニカルライティングやり方

https://qiita.com/yasuoyasuo/items/c43783316a4d141a140f?utm_campaign=popular_items&utm_medium=feed&utm_source=popular_items

列挙型

全体像→列挙1→列挙2→まとめ

主張型

背景→主張→理由→具体例→予想される反論への共感→再び主張

結論優先型

結論→理由と根拠→具体例→まとめ 序論→本論→結論

エピソードx気づき型

エピソード→気づき→結論

提案・紹介型

背景→提案・紹介→提案・紹介の理由→方法論→まとめ

http://www.yu-hanami.com/entry/2017/12/19/170200

ビジネス文書

ビジネス文書の目的は、

  • 相談
  • 報告
  • 依頼 のどれかに大分類される。

『総方位』と覚える

文書の種類 内容 文書例 作成量
認識共有 特定の範囲の人間との認識を同じくするための文書。主に目的、作法、ルールなどを記述する ･計画書
･規約
・標準文書
・技術ノウハウ集
 少
認識共有 特定の範囲の人間との認識を同じくするための文書。主に目的、作法、ルールなどを記述する ･計画書
･規約
・標準文書
・技術ノウハウ集
 少
情報伝達 ある人間の考えを別の人間に伝えるための文書。主に業務仕様、機能仕様、プログラム仕様などを記述する ･設計書
・テスト仕様書		 多
証左 ある出来事が確かに起きた、起こしたという記録を残すための文書。主に事実、出来事、結果などを記述する ･テスト結果
･議事録		 中～多

文書作成のポイント

  • 文書を作成するのはなぜか？ （目的）

  • 誰に読んでもらうのか？ （対象）

  • 何を伝えたいのか？ （趣旨）

  • どういうストーリーにするか？ （構成）

  • 文書をいつまでに作成するか？ （納期）

  • どこまでの範囲の文書か？（適用範囲）

  • なにをもとに作成したのか？（関連文書）

チェックリスト

  • 文書の構成に関するルール
  • ルール 1-1：文書の作成目的を明確にしているか？ 論点を絞っているか？
  • ルール 1-2：結論を先に、理由を後に記載しているか？
  • ルール 1-3：理由は「漏れなく、ダブりなく（MECE）」となっているか？
  • 文書の体裁・表現に関するルール
  • ルール 2-1：1 文は 50 字以内におさまっているか？
  • ルール 2-2：見ただけで概要が分かる文書となっているか？
  • ルール 2-3：曖昧な言葉で逃げていないか？
  • ルール 2-4：読み手の誤解を招く表現を使用していないか？ 用語は統一されているか？
  • 文書作成プロセスに関するルール
  • ルール 3-1：文書の設計図を作ったか？
  • ルール 3-2：設計図について上司と合意したか？
  • ルール 3-3：設計図をもとに文書を作成し、上司がレビューしたか？
  • ルール 3-4：作成した文書の中から再利用できる部分を抽出して整理したか？

図・表

図、表の記載方法

http://home.hiroshima-u.ac.jp/er/Etc_R_R_Z2.html

http://www.kumikomi.net/archives/2010/09/ep26doc2.php

appendix（付録）の場合はFigure A...B, Table A...B とかが一般的な模様

グラフの選び方

https://material.io/design/communication/data-visualization.html#

ドキュメントの質を上げるには

  1. 1つの事柄だけを伝える文章にする
  2. 修飾語を短くする
  3. 述語を主語の近くに記述する
  4. 主語を省略できるかできないかを判断する
  5. 条件節の後には肯定形を使う
  6. 二重否定を使わない
  7. 部分否定を使わない
  8. 「～のように」と否定形の組み合わせを使わない
  9. 能動態の文章にする
  10. 読点をうまく使うと意味が明確な文章になる
  11. 個条書きを使って分かりやすい文章にする

http://www.atmarkit.co.jp/ait/articles/0912/21/news095.html

計画書

記載項目 概要
目的 工程のゴールと目的
目的 工程のゴールと目的
優先事項 工程で最も優先すべき基準（品質、納期、コストなど）。各種の問題が発生した際の判断基準になる
事前共有知識 工程の従事者が事前に知っておくべきことと、目を通しておくべき資料の説明
作業手順 作業の流れ、インプットとアウトプット
作成する成果物 アウトプットの種類、管理方法を明確に指定。記述レベルに言及する場合も（連載次回以降で説明予定）
進ちょく管理方法 進ちょく管理の方法、進ちょく基準、管理文書の管理方法
工程スケジュール 大まかなマスタスケジュールとマイルストーン
コミュニケーションフロー 課題発生時の対応手順と情報共有の方法
工程完了条件 可能な限り定量的な指標による完了条件
品質管理方法 レビュー方法、成果物、テスト密度など
体制と役割 チームやプロジェクトの体制と役割、責任範囲

ドキュメント体系

基準：基本方針を示した資料

マニュアル：開発標準に組み込むための方法について説明した資料

ガイド：技術的な内容について説明した資料

報告書

アジェンダ

アジェンダサンプル

議事録

  • 議事録
  • 誰が
  • 何を
  • いつまでに
  • なぜ
  • どのようにするのか

議事録サンプル

作業報告

作業報告項目サンプル

設計書

1章に書くべき内容

Case1

  • 総則（はじめにとか概要とかでもよい？）
  • （はじめに）背景を言いたいとき？背景でもよい？
  • 目的
  • 適用範囲（前提とかとも言われるけど、適用範囲の中に記述する）
  • 関連文書
  • 用語の定義

Case2

  • はじめに
  • 目的
  • 適用範囲（前提とかとも言われるけど、適用範囲の中に記述する）
  • 関連文書
  • 用語の定義

その他

  • 文書の位置付け

  • 付録

JAXA共通技術文書を元に定義した。

論文

  • 表題 （Title）
  • 概要 （Abstract）
  • 目次 （Contents）
  • 序論（Introduction）
  • 背景（Background）
  • 目的（Objectives）
  • 対象と方法 （Observations,Methodsとか）
  • 結果（Results）
  • 考察 （Discussion）
  • 結論 （Conclusion/Summary）
  • 謝辞 （Acknowledgments）
  • 参考文献 （References）
  • 付録 （Appendix）

規約

Definition:

Pros:

Cons:

Decision:

リファレンス

関数、クラス

  • 概要
  • 構文、書式(APIの使い方)
  • 引数
  • 戻り値
  • エラー
  • 備考
  • 使用例

"DocomoのAPIリファレンス":https://dev.smt.docomo.ne.jp/?p=index

"Java":http://docs.oracle.com/javase/jp/7/api/

REST

  • URL
  • リクエストメソッド
  • フォーマット(json,xml)
  • パラメーター
  • レスポンス
  • サンプル

お預り証

お預り証サンプル

技術ログ

  • 仕事で開発したライブラリ、ミドルウェアについて
  • 開発の工夫
  • エンジニア採用の工夫
  • 業務フローの改善
  • 勉強会で発表したよ、的な報告
  • エンジニアの生活
  • QAのこと
  • CSのこととかもあってよいかも

図の使い分け

https://gramener.github.io/visual-vocabulary-vega/

カタカナ語・外来語統一

JTCA

http://www.jtca.org/ai_collaboration/katakana_wg/katakana_guide.pdf

文科省

http://www.mext.go.jp/b_menu/hakusho/nc/k19910628002/k19910628002.html

文書作成時のポイント

  • 設定、制約、禁止事項を意識して記述する

テクニック

ディレクトリ一覧作成

tree . | sed 's/q//g' | sed 's/?//g' | sed 's/ / /g' > /tmp/csv_dir.txt

Excelに貼り付け->区切り->スペース->連続した区切りオフ

列の幅 1

昔の

tree --charset=C . | sed 's/--/-/' | sed 's/ / /g

tree . | sed 's/笏�//g' | sed 's/ﾂ//g' | sed 's/ / /g' > /tmp/spice_dir8.txt

その他

表記ルール

ひらがな・漢字ルール

Before After
行う おこなう　または　する
行う おこなう　または　する
出来る できる（「出来上がる」の場合は漢字）
易く やすく
達 たち
尚更 なおさら
揃って そろって
等 など
為 ため
時 とき
事 こと
凄い すごい
〜して下さい 〜してください（「飴を下さい」は漢字）
〜して頂く 〜していただく（「飴を頂く」は漢字）
様々 さまざま
色々 いろいろ
但し ただし
無い ない
有る ある
予め あらかじめ
致します いたします
敢えて あえて
入れる いれる
伴い ともない

複数の書き方

読み込み （読込機能）など漢字のみの場合はこれも可とする

取り扱い （取扱説明書）など漢字のみの場合はこれも可とする

感嘆符！？ルール

感嘆符のあとはスペースを空ける

http://liginc.co.jp/life/useful-info/127238

関連文書、適用文書、参考文書、

文書が上下関係ならば適用文書、並列（３つで１つのドキュメントなど）ならば参考文書。

適用文書とするものは、本書の一部となる。参考は本書作成にあたり参考にしたものである。

準拠文書は、要求内容を詳細化および具体化した文書である。

関係は

+関連文書
|
+----準拠文書
|
+----適用文書
|
+----参考文書

半角・全角使い分け

wikipediaの"表記ガイド":http://ja.wikipedia.org/wiki/Wikipedia:%E8%A1%A8%E8%A8%98%E3%82%AC%E3%82%A4%E3%83%89 を参考としている

記号（ ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ ] ^ _ ` { | } ~ ）、数字、アルファベットをどうするか？

  • 数字、アルファベットは半角を使用する ->見栄え的に全角はカッコ悪いため

  • ! ( ) : ? [ ]は基本的に全角を使う場合がある(要検討!!) ->もはや記号というより文字なので

->前の文書が半角の場合は半角とする

  • （）の半角全角 (要検討!!) ->括弧は中身が日本語には、全角括弧（）を用いる

->括弧は中身が半角英数字には、半角括弧()を用いる。括弧の外側にスペースを空けること () 。

  • ～は-とする
  • その他の記号は全て半角とする

いろんな意見

  • 全角英数字はアクセシビリティに欠ける
  • 全角英数字は検索エンジンやその他システムに認識されにくく再利用性が低い
  • 全角英数字は禁則処理が行われない
  • 半角英数字のほうが文字化けのリスクが少なく、日本語フォントがなくても閲覧できる
  • 半角英数字のほうがバイト数が低い（容量が軽い）

A.全角記号を使う立場

だって半角記号じゃ日本語にあわないもん。ベースラインが若干低めだし、記号の前後に余裕がないからそこだけ詰まった感じになるし。欧文みたいに記号の前後にスペースいれればいいかもしれないけど、それは日本語文にコンマやピリオドを使うみたいな違和感がある。

Unicodeにも互換のためとはいえ全角文字入ってるから、今後も使っていいんじゃないの？印刷とかするんだったら、やっぱり全角で入れたといたほうが楽なんじゃない？なんらかの理由で半角にしなきゃいけないんだったら、単純に置換してしまえばすむはずだし。

全角・半角の使い分けを統一できないのは個々人の問題だし、なんらかのチェックツールを使えば済むんじゃないの？欧米圏のシステムが対応してないのもそのシステムが悪いだけの問題だし、そもそもそれで困るケースなんてのは少ない。

B.全角記号を使わない立場

そもそも全角・半角ってのが解せない。テキストデータは文字の抽象的な意味を示すのであって、見栄えをコントロールするのはブラウザやワードプロセッサの役割だ。

Unicodeに全角記号が入ってるのは、「過去の」文書との互換性を保つためであって、今後新しい文書で使うべきではない。印刷などで、使い分ける必要があるなら、それは印刷用のソフトウェアが対応するか、それこそチェックツールを使えばいい。

それより印刷のことを言うなら、全角・半角が統一されてない(括弧の始まりが全角で終わりが半角になってたりとか)ほうが見栄えが悪い。