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
「エンジニアのための ドキュメントライティング」書籍のすすめ / phpconfuk 2023
Search
gorou_178
June 24, 2023
Technology
2
1.1k
「エンジニアのための ドキュメントライティング」書籍のすすめ / phpconfuk 2023
「エンジニアのためのドキュメントライティング」書籍を読んでとても感動したので、一部抜粋してドキュメントを書くうえで大切なことなどをまとめました。
gorou_178
June 24, 2023
Tweet
Share
More Decks by gorou_178
See All by gorou_178
Spring Bootで作成したAPIテストのコスパを高めよう!
gorou_178
1
1.2k
EventBridgeの運用について
gorou_178
0
230
Stripe Appsと自サービスの連携作法
gorou_178
0
220
Laravelのsession設定を変えて 劇的にパフォーマンスを改善した話
gorou_178
0
2k
Stripeとアプリケーションの関係を可視化してみた
gorou_178
0
880
Stripeでの増税対応
gorou_178
0
820
Stripe+PHPでセキュアで安全な決済機能を作る
gorou_178
0
1.8k
Stripeを利用した決済機能をテストする
gorou_178
1
5.7k
tenpuでのStripe活用事例
gorou_178
0
340
Other Decks in Technology
See All in Technology
Tableau API連携の罠!?脱スプシを夢見たはずが、逆に依存を深めた話
cuebic9bic
3
210
LIFF CLIとngrokを使ったLIFF/LINEミニアプリのお手軽実機確認
diggymo
0
230
解消したはずが…技術と人間のエラーが交錯する恐怖体験
lamaglama39
0
190
私とAWSとの関わりの歩み~意志あるところに道は開けるかも?~
nagisa53
1
160
Foundation Model × VisionKit で実現するローカル OCR
sansantech
PRO
0
290
製造業の課題解決に向けた機械学習の活用と、製造業特化LLM開発への挑戦
knt44kw
0
150
Vision Language Modelと自動運転AIの最前線_20250730
yuyamaguchi
3
1.1k
alecthomas/kong はいいぞ
fujiwara3
6
1.4k
【OptimizationNight】数理最適化のラストワンマイルとしてのUIUX
brainpadpr
0
200
ビジネス文書に特化した基盤モデル開発 / SaaSxML_Session_2
sansan_randd
0
260
生成AI時代におけるAI・機械学習技術を用いたプロダクト開発の深化と進化 #BetAIDay
layerx
PRO
1
1k
SRE新規立ち上げ! Hubbleインフラのこれまでと展望
katsuya0515
0
160
Featured
See All Featured
The Straight Up "How To Draw Better" Workshop
denniskardys
235
140k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
161
15k
4 Signs Your Business is Dying
shpigford
184
22k
Bootstrapping a Software Product
garrettdimon
PRO
307
110k
Documentation Writing (for coders)
carmenintech
73
5k
It's Worth the Effort
3n
185
28k
Fireside Chat
paigeccino
38
3.6k
A Tale of Four Properties
chriscoyier
160
23k
The Cost Of JavaScript in 2023
addyosmani
51
8.7k
Typedesign – Prime Four
hannesfritz
42
2.7k
jQuery: Nuts, Bolts and Bling
dougneiner
63
7.8k
Making Projects Easy
brettharned
117
6.3k
Transcript
ΤϯδχΞͷͨΊͷ υΩϡϝϯτϥΠςΟϯάॻ੶ͷ͢͢Ί 2023/06/24 PHPΧϯϑΝϨϯεԬ2023 @gorou_178
• @gorou_178 • BaaS(Bank as a Service)ͷ։ൃ • ϥϯχϯά •
ίʔώʔͱϓϦϯ • θϧμ৽࡞ϓϨΠத ࣗݾհ
ࠓͷΰʔϧ • υΩϡϝϯτΛॻ͘ͱ͖ͷେࣄͳϙΠϯτ͕ཧղͰ͖Δ • υΩϡϝϯτ੍࡞ʹ͓͍ͯɺސ٬ࢹ͕େࣄͰ͋Δ͜ͱ͕Θ ͔Δ
͘͡ • ॻ੶ͷհ • υΩϡϝϯτཧ • ಡΈखͱॻ͖खͷཧղ • υΩϡϝϯτͷ࣭ •
υΩϡϝϯτϥΠςΟϯάͰେͳϙΠϯτ
ॻ੶ͷհ
• ݪஶʮDocs for Developersʯͷຊޠ༁ • ࠓ3݄͝Ζग़൛ • ΤϯδχΞ͕࡞ͬͨΓɺར༻͢ΔυΩϡϝ ϯτʢAPI༷ॻɺखॱॻͳͲʣʹର͢Δ ॻ͖ํͳͲΛઆ໌ͨ͠ຊ
ΤϯδχΞͷͨΊͷυ ΩϡϝϯτϥΠςΟϯά
ॻ੶ͷհ ΤϯδχΞ͚ʹॻ͔Εͨॻ੶ ͔͠͠ɺॻ͔Ε͍ͯΔυΩϡϝϯτͷ࡞ɾӡ༻ϊϋ͍Ζ Μͳਓ͕׆༻Ͱ͖Δʢͱࢲࢥͬͨʣ Ұ෦Λൈਮɾ·ͱΊͯհ
υΩϡϝϯτཧ
υΩϡϝϯτϓϩμΫτ • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ • ·ͣॻ͍ͯΈΔʢ։ൃɾςετʣ • ಡΜͰΒͬͯϑΟʔυόοΫΛΒ͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ • ཧղ͍͢͠Α͏ʹ࠶ฤू ≒
ϦϑΝΫλϦϯά • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
υΩϡϝϯτϓϩμΫτ • ΈΜͳ͕΄͕͍ͬͯ͠ΔυΩϡϝϯτΛཧղʢԾઆݕূʣ • ·ͣॻ͍ͯΈΔʢ։ൃɾςετʣ • ಡΜͰΒͬͯϑΟʔυόοΫΛΒ͍վળ͢ΔʢϦϦʔεɺϨϏϡʔɺमਖ਼ɺݕূʣ • ཧղ͍͢͠Α͏ʹ࠶ฤू ≒
ϦϑΝΫλϦϯά • ϓϩμΫτ։ൃͷྲྀΕͱಉ͡
υΩϡϝϯτͷސ٬ = ಡΈख ಡΈखͷࣄΛཧղ͢Δࣄ͕େ
ಡΈखͱॻ͖खͷཧղ
• ʮଞਓ͕ࣗͱಉࣝ͡Λ͍࣋ͬͯΔʯ • ͱࢥ͍ࠐΜͰ͍ΔೝόΠΞεͷ͜ͱ • →ॻ͖ख͜ͷढ͍ΛஅͪΔඞཁ͕͋Δ ࣝͷढ͍
• ಡΈखใΛ୳ͯ͠υΩϡϝϯτʹͨͲ Γண͘ • ಡΈखॻ͍ͯ͋Δ༰Λ΄ͱΜͲಡ·ͳ ͍ • ͜ͷໃ६Λཧղͯ͠͏·͘׆༻͢Δඞཁ͕ ͋Δ ಡΈखͷཧղ
ͰɺͲͷΑ͏ʹॻ͖͔͘
υΩϡϝϯτ࣭ΛߴΊΔΑ͏ʹॻ͘
υΩϡϝϯτ࣭ • ػೳ࣭ͱߏ࣭ʹղ͞ΕΔ • ػೳ࣭: υΩϡϝϯτͷతΰʔϧ͕ୡ͞Ε͍ͯΔ͔Ͳ͏͔ • ߏ࣭: υΩϡϝϯτࣗମ͕͏·͘ߏ͞Ε͍ͯΔ͔Ͳ͏͔
ػೳ࣭ͱߏ࣭ • ػೳ࣭ • త͕͋Δ͜ͱ • ΞΫηγϏϦςΟ͕͋Δ͜ͱ • ݟ͚͍ͭ͢͜ͱ •
ਖ਼֬Ͱ͋Δ͜ͱ • શͰ͋Δ͜ͱ • ߏ࣭ • Clear(໌֬ͳ) • Concise(؆ܿͳ) • Consistent(Ұ؏͍ͯ͠Δʣ υΩϡϝϯτͷతΛୡ͠ͳ͚ΕෆेͳυΩϡϝϯτ →ͦͷͨΊɺػೳ࣭͕ΑΓॏཁ
ػೳ࣭ΛߴΊΔͨΊͷ େͳϙΠϯτ
1. λΠτϧͱ಄͕େ
1. λΠτϧͱ಄͕େ • ೦ͳ͕ΒυΩϡϝϯτશͯಡ·Εͳ͍ • υΩϡϝϯτͷλΠτϧʮ͜ΕΛಡΉͱୡͰ͖ΔΰʔϧΛཁͨ͠ͷʯʹ͖͢ • λΠτϧͱ಄Ͱʮ͜ΕΛಡΉ͖͔ʯ͕Θ͔Δ • ඦฉҰݟʹ͔ͣ͠
• ΠϥετਤΛೖΕΔͱཧղ͍͢͠ • ΠϥετΛؚΉࢦࣔॻ vs ΠϥετΛؚ·ͳ͍ࢦࣔॻɺΠϥετΛؚΉࢦࣔॻͷํ͕3ഒ͕Α͔ͬͨ • ݟͨͷѱ͞ʹΑͬͯɺಡΈखίϯςϯπͷڵຯΛࣦ͏͜ͱ͕͋Δ
2. ݟग़͠ಓ͠Δ
2. ݟग़͠ಓ͠Δ • ಡΈखͲΜͲΜಡΈඈ͢ • Ͱ͋Εɺݟग़͠ΛυΩϡϝϯτͷతʢಓ͠Δʣͱͯ͠ػೳͤ͞Δ • ඞཁͰͳ͍ͷಡΈඈ͠ɺඞཁͳใʹҰؾʹͨͲΓண͚Δ(VoiceOverͷݟग़͠δϟϯϓػೳ) • ݟग़͠ͰؾΛ͚ͭΔϙΠϯτ
• ؆ܿɾ໌֬ɾ۩ମతʹ͢Δ • ࠷ॏཁͳใ͔Β࢝ΊΔ • ॏෳͷͳ͍ݟग़͠Λ࡞Δ • Ұ؏ੑΛอͭ
3. Ұ؏ੑ
3. Ұ؏ੑ • ༻ޠͷҰ؏ੑ • ༻ޠͷҰ؏ੑ͕ͳ͍ͱɺϓϩμΫτΛఏڙ͢Δ৫͕ɺ༻ޠͷఆٛʹ֬৴Λ͍࣋ͬͯͳ͍͜ͱΛࣔ͢ • Ϣʔβͷ৴པੑΛԼͤ͞Δ • ݟग़͠ͷҰ؏ੑ
• ॻ͖ํɺॱংͳͲʹҰ؏ੑΛ࣋ͨͤΔ͜ͱͰಡΈखΛ໎Θͤͳ͍ ͜ͷॻ੶શମͱͯ͠ʮҰ؏ੑʯ͕ࢁग़ͯ͘ΔͨΊͱͯେͳϙΠϯτ →Ұ؏͍ͯ͠Δ͜ͱͰಡΈखͷཧղΛ͛ͳ͍
·ͱΊ
·ͱΊ • υΩϡϝϯτϓϩμΫτ։ൃͱಉ͡ʢυΩϡϝϯτϓϩμΫτ։ൃͷҰ෦ʣ • υΩϡϝϯτΛॻ͘ʹɺಡΈखͷཧղ͕ඞཁ • ސ٬ࢹɺେࣄ • ಡΈखΛ૾ͯ͠ɺཧղ͍͢͠υΩϡϝϯτΛॻ͍͍ͯ͜͏ •
ʮཧղ͍͢͠ʯʹϋʔυϧΛײ͡ΔํɺԿͰΑ͍ͷͰͻͱ·ͣॻ͘ʂJust Do Itʂ • λΠτϧɾݟग़͠ɾҰ؏ੑ͕େࣄ • ΈΜͳͰυΩϡϝϯτΛҭͯΒΕΔπʔϧαʔϏεΛར༻͢ΔͱΑΓΑͦ͞͏ • ͱ͓ͯ͠Ζ͍ͷͰॻ੶ΑΜͰΈ͍ͯͩ͘͞
Appendix • ҹʹͬͨ෦ͷࡶͳϝϞ • ϓϥογϯά(plussing) • ϐΫαʔɾΞχϝʔγϣϯɾελδΦͰ࠾༻͞Ε͍ͯΔϑΟʔυόοΫํ๏ • ʮݐઃతͳՃఏҊ͕Ͱ͖ΔͳΒɺΞΠσΞΛ൷ͯ͠Α͍ʯ •
τΠϧͷଘࡏΛཧղͰ͖ͳ͚ΕɺͦͷτΠϧΛࣗಈԽͯ͠ͳͤ͘ͳ͍ • ࣗಈԽͳͲযΒͣγϯϓϧͳํ๏Ͱ·ͣࢼͯ͠ΈΔ