Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
ドキュメント、書けてますか?
Search
Sponsored
·
Your Podcast. Everywhere. Effortlessly.
Share. Educate. Inspire. Entertain. You do you. We'll handle the rest.
→
WATANABE Yuki
June 30, 2021
Programming
0
120
ドキュメント、書けてますか?
WATANABE Yuki
June 30, 2021
Tweet
Share
More Decks by WATANABE Yuki
See All by WATANABE Yuki
速いクイックソート: Pattern-defeating quicksort
magicant
0
410
C++ はなぜあんなにも複雑なのか
magicant
0
87
鉄道シミュレーターで自動運転を実装した話
magicant
0
320
Other Decks in Programming
See All in Programming
AI 駆動開発ライフサイクル(AI-DLC):ソフトウェアエンジニアリングの再構築 / AI-DLC Introduction
kanamasa
11
5.8k
ZJIT: The Ruby 4 JIT Compiler / Ruby Release 30th Anniversary Party
k0kubun
1
380
AtCoder Conference 2025
shindannin
0
980
ELYZA_Findy AI Engineering Summit登壇資料_AIコーディング時代に「ちゃんと」やること_toB LLMプロダクト開発舞台裏_20251216
elyza
2
1.2k
コントリビューターによるDenoのすゝめ / Deno Recommendations by a Contributor
petamoriken
0
190
從冷知識到漏洞,你不懂的 Web,駭客懂 - Huli @ WebConf Taiwan 2025
aszx87410
2
3.4k
Basic Architectures
denyspoltorak
0
580
Data-Centric Kaggle
isax1015
2
690
HTTPプロトコル正しく理解していますか? 〜かわいい猫と共に学ぼう。ฅ^•ω•^ฅ ニャ〜
hekuchan
2
660
OSSとなったswift-buildで Xcodeのビルドを差し替えられるため 自分でXcodeを直せる時代になっている ダイアモンド問題編
yimajo
3
460
コマンドとリード間の連携に対する脅威分析フレームワーク
pandayumi
1
410
AIによるイベントストーミング図からのコード生成 / AI-powered code generation from Event Storming diagrams
nrslib
2
1.6k
Featured
See All Featured
Keith and Marios Guide to Fast Websites
keithpitt
413
23k
How to Build an AI Search Optimization Roadmap - Criteria and Steps to Take #SEOIRL
aleyda
1
1.8k
30 Presentation Tips
portentint
PRO
1
190
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
162
16k
SEO Brein meetup: CTRL+C is not how to scale international SEO
lindahogenes
0
2.3k
Joys of Absence: A Defence of Solitary Play
codingconduct
1
270
HU Berlin: Industrial-Strength Natural Language Processing with spaCy and Prodigy
inesmontani
PRO
0
150
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
12
1.4k
Un-Boring Meetings
codingconduct
0
180
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
141
34k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
35
2.3k
WENDY [Excerpt]
tessaabrams
9
35k
Transcript
ドキュメント、書けてますか? 渡邊裕貴 / 2021-06-30
ドキュメントとは 当たり前すぎてかえって正確な定義を言いにくい気がするが ここでは 「業務に役立つ情報を記載した文書や図」 としておく
とある人の意見 プログラマーがドキュメントを書かない理由 (和訳が怪しいところがあるので原文を読んだ方が良い ) • 書くことは難しいから • ドキュメントは納品すべき成果物ではないから • 書くための良いツールがないから
書くことは難しい • 業務に役立つ情報を書くことは難しい • コーディングよりも難しい なぜなら • 情報を整理し言語化するやり方は自明ではない • 自然言語の文章に問題があってもエラーは出ない
難しさを正しく認識する 綺麗なコードを書けないとき • ❌ コメントやドキュメントで理解を助ける • ⭕ コメントやドキュメントを読むともっと分からなくなる • 綺麗なコードを書けない人は綺麗なドキュメントも書けない
難しさを正しく認識する 2 • ❌ 書く時間がないから書けない • ⭕ 書くスキルがないから書けない • 人は、自分ができることだけをやろうとしがち
◦ スキルがないと、所要時間の見積もりもできないので敬遠する • 書くスキルを持つ人は、自ら書く時間を作ろうとする
メンテナンスは書くことよりも難しい ドキュメントのメンテナンスはコードのメンテナンスよりも難しい コードと同様に、ドキュメントも • 設計をよく考えろ • 継続的にリファクタリングしろ
難易度に応じて担当者を決める 多数の文書や図からなる全体の構成を整理する 一つの文書の中身の構成を整理する 要件と仕様と設計の関連が理解できる説明を書く 比較的複雑な機能の動作の解説を書く 細かい機能の動作の解説を書く 既に書かれた文章の誤りを訂正する 難 易 全員ができる必要はないが
誰もできないのは困る
やっていこう • 自分ができることをやろう • 自分ができることを増やそう ◦ 練習しよう • 良いドキュメントとはどのようなドキュメントか? ◦
考えよう ◦ みんなで話し合おう 書けない 書かない