今すぐ改善 誤解を生まない技術文書にするプチテクニック

今すぐ改善☆
誤解を生まない技術文書にする
プチテクニック
～ETロボコン提出モデルから考えるUML図の活用法～
ETロボコン北陸地区実行委員会 技術委員
チェンジビジョン 製品事業部
松田友里
自己紹介
◦ 松田友里（りりぃ）
◦ 自称「ロリィタプログラマー」
◦ チェンジビジョンでastah*を開発
◦ 「ETロボコン」の元チャレンジャー
◦
◦
◦
◦
2015/11/20
2009年関西地区大会：シルバーモデル
2010年北陸地区大会：総合3位
2011年CS大会に出場
2014年から北陸地区の実行委員をしている
誤解を生まない技術文書にするプチテクニック
2
技術文書って何？
◦ 他人に何らかの情報を伝えるための文書
設計書
説明書
論文
報告書
レシピ
etc…
◦ もちろん「ETロボコン提出モデル」も含まれます
2015/11/20
誤解を生まない技術文書にするプチテクニック
3
ETロボコンの提出モデルって何？
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
4
ETロボコンの提出モデルって何？
どんな機能があるのか
実際に実装できるか
どう動くのか
それって
設計資料？
が分かるモデル
◦ 設計資料を主に使うのは「実装」担当者
◦ 実装担当者に向けた設計資料
2015/11/20
誤解を生まない技術文書にするプチテクニック
5
設計資料はどう使われるの？
設計担当者
設計する
2015/11/20
実装担当者
実装する
[設計資料の
要件を満たした]
誤解を生まない技術文書にするプチテクニック
6
もしも設計資料に問題があったら
設計担当者
設計する
実装担当者
実装する
[設計資料の
要件を満たした]
[設計資料に
誤解される表現あり]
[理解不能]
[誤解に
気づかない]
間違えて実装
答える
[回答可能]
想像で実装
[余裕あり]
[納期が近い]
問い合わせる
[回答できない]
2015/11/20
誤解を生まない技術文書にするプチテクニック
7
仕事がお互いに止まる
次の
違う仕事
仕事中断
仕事中
do / 仕事する
entry / 思い出す
do / 回答内容を考える
/ 回答する
2015/11/20
[問題に気づく]
[問い合わせあり]
実装中
do / 実装する
/ 納品
誤解を生まない技術文書にするプチテクニック
問い合わせ中
entry / 問い合わせる
do / 回答を待つ
[回答が着た]
8
今日のおはなし
◦ 説明したいことを説明できる図を描くテクニック
◦ 誤解をされない説明テクニック
◦ 誤解をされないレイアウトテクニック
を、ETロボコンの提出モデルを例に紹介します！
2015/11/20
誤解を生まない技術文書にするプチテクニック
9
説明したいことを説明できる図を
描くテクニック
2015/11/20
誤解を生まない技術文書にするプチテクニック
10
何を説明したい？
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
11
説明したいことを説明できていない？
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
12
でっかい図はダメじゃない
◦ 直接口頭で説明するポスターセッションなんかでは有効
◦ 突然やってきた人に必要なところだけ説明できる
◦ 全体を1枚の図で見渡すことができる
◦ どんなクラス、関係があるかわかる
◦ じゃあ、文書にするときも
必要なところだけ説明できるんじゃない？
2015/11/20
誤解を生まない技術文書にするプチテクニック
13
必要な要素に絞った図
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
14
伝えたいこと以外は削ってしまおう！
説明するときにいらないものを隠してみよう
説明しきれなければ足りないものを足そう
すでにあるものを整理するだけ
私にもできる！
誰でもできる！
2015/11/20
誤解を生まない技術文書にするプチテクニック
15
質問はありませんか？
2015/11/20
誤解を生まない技術文書にするプチテクニック
16
誤解をされない説明テクニック
2015/11/20
誤解を生まない技術文書にするプチテクニック
17
見出しと内容を一致させよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
18
見出しと内容を一致させよう
Before
2015/11/20
After
誤解を生まない技術文書にするプチテクニック
19
見出しと内容を一致させよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
20
見出しと内容を一致させよう
◦ 見出しが先か、内容が先か
◦ 順番はどっちでもいい
◦ とにかく見出しと内容を一致させよう！
私にもできる！
誰でもできる！
2015/11/20
誤解を生まない技術文書にするプチテクニック
21
誤解をされない説明テクニック
2015/11/20
誤解を生まない技術文書にするプチテクニック
22
用語を統一しよう
◦ 同じもの？
◦ 違うもの？
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
23
用語を統一しよう
◦ 文書全体で統一した呼び方をしましょう
◦ 同じものは同じ名前
◦ 違うものは違う名前
◦ UMLの図に限った話ではないです
私にもできる！
誰でもできる！
2015/11/20
誤解を生まない技術文書にするプチテクニック
24
質問はありませんか？
2015/11/20
誤解を生まない技術文書にするプチテクニック
25
誤解をされないレイアウトテクニック
2015/11/20
誤解を生まない技術文書にするプチテクニック
26
読みやすいフォントを使おう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
27
読みやすいフォントを使おう
2.1 基本方針
コースの各区間を”最適な方法”で走行させる。
ベーシックコースは、直線やカーブ等、それぞれ特徴
のあるエリアが連続したもので成り立ち、主にカーブ
曲率によって走行可能な最高速度が決まる[5.5 曲率に
よる最高速度]と考えられる。
エリアごとに最適な「走行パターン」の設定を行うこ
とでより高速に安定した走行ができると仮定する
Before
2015/11/20
After
誤解を生まない技術文書にするプチテクニック
28
誤解をされないレイアウトテクニック
2015/11/20
誤解を生まない技術文書にするプチテクニック
29
グループ化してみよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
30
グループ化してみよう
Before
2015/11/20
After
誤解を生まない技術文書にするプチテクニック
31
グループ化してみよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
32
グループ化してみよう
① モータの角速度[rad/sec]=(モーターの回転角度の合計(今回の測定データ)
– モーターの回転角度の合計(前回の測定データ)) × π/180
⑦ X座標の変化量 = ⑤走行体の速度 × cos(④自転角)
⑧ Y座標の変化量 = ⑤走行体の速度 × sin(④自転角)
X座標の変化量[mm]
Y座標の変化量[mm]
② タイヤの速度 [mm/sec] = ①モータの角速度 × タイヤの半径[mm]
③ 走行体が曲がる速度
= ②右タイヤの速度 - ②左タイヤの速度 / 左右の車輪の幅
④ 自転角[θ]
= ③今回の走行体が曲がる速度 × ③前回の走行体が曲がる速度 / 2
⑤ 走行体の速度[mm/sec]
= (② 右タイヤの速度 × ②タイヤの速度) / 2
⑥ 累計距離[mm]
= ⑥前回測定した距離 + ⑤走行体の速度
※測定は1sec毎に行う
2015/11/20
⑨ X座標 = ⑧前回のX座標 + (⑦今回のX座標の変化量
+ ⑦前回のX座標の変化量)/2
⑩ Y座標 = ⑨前回のY座標 + (⑧今回のY座標の変化量
+ ⑧前回のY座標の変化量)/2
⑪ 走行体の旋回角
= ⑪旋回角 + ④自転角
※⑨、⑩、⑪の基準点はスタート位置
誤解を生まない技術文書にするプチテクニック
33
誤解をされないレイアウトテクニック
2015/11/20
誤解を生まない技術文書にするプチテクニック
34
見出しは一番目立たせよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
35
見出しは一番目立たせよう
基本走行技術
Before
自立性
After
2015/11/20
デバイス要素技術
総合検証
誤解を生まない技術文書にするプチテクニック
36
見出しは一番目立たせよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
37
誤解をされないレイアウトテクニック
2015/11/20
誤解を生まない技術文書にするプチテクニック
38
順番に読めるように配置しよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
39
順番に読めるように配置しよう
Before
2015/11/20
After
誤解を生まない技術文書にするプチテクニック
40
順番に読めるように配置しよう
ETロボコン実行委員会提供
2015/11/20
誤解を生まない技術文書にするプチテクニック
41
順番に読めるように配置しよう
Before
After
2015/11/20
誤解を生まない技術文書にするプチテクニック
42
誤解をされないレイアウトテクニック
◦ 読みやすいフォントを使おう
◦ グループ化してみよう
◦ 見出しは一番目立たせよう
◦ 順番に読めるように配置しよう
私にもできる！
誰でもできる！
2015/11/20
誤解を生まない技術文書にするプチテクニック
43
りりぃメソッドも見てね
◦ astahブログ（http://ja.astahblog.com/）
◦ 特集：読みたくなるモデルを描くコツ「りりぃメソッド」を解説
【フォント編】
第一印象は全ての始まり、そのフォントで大丈夫？
【レイアウト編】
流れを見せるレイアウト、見てほしい順序で視線を動かすレイアウトとは
【強調のテクニック】
一番伝えたいことは何？ 強調のテクニック
【ひと手間編】
見た目を決めるのはそのひと手間、画像とレビューを侮るなかれ
【まとめ】
提出前の最終チェックに役立つチェックリスト
【おまけの資料集】
これを読んだらあなたもデザイナー？ お薦めの資料集
2015/11/20
誤解を生まない技術文書にするプチテクニック
44
質問はありませんか？
2015/11/20
誤解を生まない技術文書にするプチテクニック
45
まとめ
説明に必要なことだけ書きましょう
• 伝えたいこと以外は削ってしまおう
次の工程の人が見て役に立つ文書を書きましょう
• 見出しと内容を一致させよう
• 用語を統一しよう
誤解を生まないように書きましょう
• 読みやすいフォントを使おう
• グループ化してみよう
2015/11/20
• 見出しは一番目立たせよう
• 順番に読めるように配置しよう
誤解を生まない技術文書にするプチテクニック
46
誤解を生む技術文書が・・・
設計担当者
設計する
実装担当者
実装する
[設計資料の
要件を満たした]
[設計資料に
誤解される表現あり]
[理解不能]
[誤解に
気づかない]
間違えて実装
答える
[回答可能]
想像で実装
[余裕あり]
[納期が近い]
問い合わせる
[回答できない]
2015/11/20
誤解を生まない技術文書にするプチテクニック
47
誤解を生まない技術文書に
なりますように
設計担当者
設計する
2015/11/20
実装担当者
実装する
[設計資料の
要件を満たした]
誤解を生まない技術文書にするプチテクニック
48
ご清聴ありがとうございました
2015/11/20
誤解を生まない技術文書にするプチテクニック
49