Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
ドキュメント、書けてますか?
Search
Sponsored
·
Ship Features Fearlessly
Turn features on and off without deploys. Used by thousands of Ruby developers.
→
WATANABE Yuki
June 30, 2021
Programming
130
0
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
ドキュメント、書けてますか?
WATANABE Yuki
June 30, 2021
Transcript
9 slides
ドキュメント、書けてますか? 渡邊裕貴 / 2021-06-30
ドキュメントとは 当たり前すぎてかえって正確な定義を言いにくい気がするが ここでは 「業務に役立つ情報を記載した文書や図」 としておく
とある人の意見 プログラマーがドキュメントを書かない理由 (和訳が怪しいところがあるので原文を読んだ方が良い ) • 書くことは難しいから • ドキュメントは納品すべき成果物ではないから • 書くための良いツールがないから
書くことは難しい • 業務に役立つ情報を書くことは難しい • コーディングよりも難しい なぜなら • 情報を整理し言語化するやり方は自明ではない • 自然言語の文章に問題があってもエラーは出ない
難しさを正しく認識する 綺麗なコードを書けないとき • ❌ コメントやドキュメントで理解を助ける • ⭕ コメントやドキュメントを読むともっと分からなくなる • 綺麗なコードを書けない人は綺麗なドキュメントも書けない
難しさを正しく認識する 2 • ❌ 書く時間がないから書けない • ⭕ 書くスキルがないから書けない • 人は、自分ができることだけをやろうとしがち
◦ スキルがないと、所要時間の見積もりもできないので敬遠する • 書くスキルを持つ人は、自ら書く時間を作ろうとする
メンテナンスは書くことよりも難しい ドキュメントのメンテナンスはコードのメンテナンスよりも難しい コードと同様に、ドキュメントも • 設計をよく考えろ • 継続的にリファクタリングしろ
難易度に応じて担当者を決める 多数の文書や図からなる全体の構成を整理する 一つの文書の中身の構成を整理する 要件と仕様と設計の関連が理解できる説明を書く 比較的複雑な機能の動作の解説を書く 細かい機能の動作の解説を書く 既に書かれた文章の誤りを訂正する 難 易 全員ができる必要はないが
誰もできないのは困る
やっていこう • 自分ができることをやろう • 自分ができることを増やそう ◦ 練習しよう • 良いドキュメントとはどのようなドキュメントか? ◦
考えよう ◦ みんなで話し合おう 書けない 書かない
More Decks by WATANABE Yuki
See All by WATANABE Yuki
速いクイックソート: Pattern-defeating quicksort
magicant
0
490
C++ はなぜあんなにも複雑なのか
magicant
0
110
鉄道シミュレーターで自動運転を実装した話
magicant
0
400
Other Decks in Programming
See All in Programming
React Native에 현대적인 빌드 도구 더하기: Rollipop 구현기
leegeunhyeok
0
180
React Native経験者が Flutterを30⽇間触って驚いたこと
3saito
0
190
作れるエンジニアから、価値を届けるエンジニアへ
ryunakayama
1
290
[Kotlin Fest 2026] eBPF Tracing for Kotlin
takehaya
1
200
Zero-Tap Sign-In対応、結局何をすればいいの?
mitohato14
0
2.1k
AIで開発が速くなった先で、開発チームは何を目指すか
shihochan
1
2.1k
protojson における文字化けの扱い
kazuki1023
0
430
Secure Your Coding Agent Like It’s Malware (v1.5) 🇬🇧 @Code.talks 2026
richargh
0
150
Spec-Driven Development - Why Vaadin Is the Perfect Fit
simas
PRO
0
250
疎結合とは何か?ソフトウェア設計における結合バランスについて考える #phpcon_niigata
kajitack
1
180
なぜ私たちは「現時点では」KMPの導入を見送ったのか
chigichan24
0
240
Getting Started with Vibe Coding
miccheng
0
230
Featured
See All Featured
Conquering PDFs: document understanding beyond plain text
inesmontani
PRO
4
3.3k
SERP Conf. Vienna - Web Accessibility: Optimizing for Inclusivity and SEO
sarafernandez
2
1.7k
A Tale of Four Properties
chriscoyier
163
24k
The Cult of Friendly URLs
andyhume
79
7.1k
Code Reviewing Like a Champion
maltzj
529
40k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
47
8.4k
Design in an AI World
tapps
1
390
The Invisible Side of Design
smashingmag
301
52k
No one is an island. Learnings from fostering a developers community.
thoeni
21
3.9k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
46
3.1k
Stop Working from a Prison Cell
hatefulcrawdad
274
21k
Collaborative Software Design: How to facilitate domain modelling decisions
baasie
1
380