用語説明の悩みをマークダウンの機能拡張で解決した話 / How we solved the problem of terminology explanation with markdown extension

ドキュメントを書いているとき、そのページ内で初めて出てきた用語をどこまで説明するか迷ったことはありませんか？私はあります！たとえば「メッセージスタンプで、○○ができるようになりました」と書こうとして「そもそもメッセージスタンプとは何かを説明した方がいいだろうか？いや、もっと手前のスタンプとは何かから説明した方がいい？でもこれを読むときにはその前提は理解しているかな。いちいち用語を解説していたら説明が長くなってしまう…でも用語説明しないと分からない人がいるかも…」と悩んでしまうことがありました。このセッションでは、そんな用語説明の悩みをVue.jsコンポーネントによるマークダウンの機能拡張で解決した話をします。

堀越 良子 / LINE株式会社 テクニカルライター。元インフラエンジニア。ねこが好き。
https://twitter.com/mochikoAsTech

※以下イベントの発表資料です。
https://line.connpass.com/event/233484/

Transcript

1. LINE Technical Writing Meetup vol. 9 ⽤語説明の悩みを マークダウンの機能拡張で解決した話 LINE Corporation Developer Content Team Yoshiko Horikoshi 20th January 2022 19:00-21:00
2. 1: ⽤語説明の悩みを マークダウンの機能拡張で解決した話 2: 伝わる⽂章を考えるために 〜テクニック以外に⼤切なことは︖〜 3: Questions and Answers 20th January 2022 19:00-21:00 LINE Technical Writing Meetup vol. 9
3. 発表資料はSlideShareでも公開しますので 発表内容や画⾯キャプチャ、動画のURLなどは ⾃由にツイートしてください
4. ⾃⼰紹介
5. はじめまして 「ほりこし」です
6. LINE Corporation Developer Content Team
7. 2020年1⽉から LINEでテクニカルライター
8. Yoshiko Horikoshi @mochikoAsTech プログラマ（3年） 広報（4年） インフラエンジニア（7年） 2020年1⽉からLINEでテクニカルライター
9. 「テクニカルライターってなに︖」と思ったら LINEの開発者向けドキュメントを⽀える 「テクニカルライティング」の専⾨チーム というセッションの動画と記事をどうぞ https://www.youtube.com/watch?v=HjKvDK50iY0 https://logmi.jp/tech/articles/325624
10. 今⽇話す内容
11. 突然ですが…
12. 機能や⼿順や仕組みについての 説明を書いているとき その説明の中で初めて出てきた⽤語を どこまで説明するか 迷ったことはありませんか︖
13. あるある︕ という⼈は挙⼿
14. 新しいLIFFスターターアプリは、現時点では vanilla JavaScriptのみをサポートしています。 今後、Next.jsやNuxtといった JavaScriptフレームワークについても サポートする予定です。 https://developers.line.biz/ja/news/2021/11/02/new-liff-starter-and-playground/
15. https://developers.line.biz/ja/news/2021/11/02/new-liff-starter-and-playground/
16. 新しいLIFFスターターアプリは、現時点では vanilla JavaScriptのみをサポートしています。 今後、Next.jsやNuxtといった JavaScriptフレームワークについても サポートする予定です。 https://developers.line.biz/ja/news/2021/11/02/new-liff-starter-and-playground/
17. vanilla JavaScript という⽤語⾃体は 各社のドキュメントにも出てくる （おそらく）⼀般的な⽤語
18. vanilla JavaScript とは何かを説明すべきか︖
19. https://developers.line.biz/ja/news/2021/11/02/new-liff-starter-and-playground/
20. vanilla JavaScript という⽤語を使わずに 「純粋な」「ただの」 JavaScriptと書くか︖
21. 説明すべきか 説明せざるべきか︖
22. 機能や⼿順や仕組みについての 説明を書いているとき その説明の中で初めて出てきた⽤語を どこまで説明するか迷う
23. 今⽇のセッション︓ ⽤語説明の悩みを マークダウンの機能拡張で解決した話
24. 説明の中で初めて出てきた⽤語を どこまで説明するか迷う…という悩みを LINE Developersサイトでは こんな⾵に解決しました
25. LINE Developersサイト https://developers.line.biz/
26. はじまり はじまり︕
27. https://developers.line.biz/ja/news/2021/11/09/messaging-api-update/
28. メッセージスタンプで ユーザーが⼊⼒したテキストを 取得できるようになりました
29. ちょっと 本筋から脱線
30. Messaging APIとは︖
31. https://www.linebiz.com/jp/manual/OfficialAccountManager/gain-friends/
32. LINE公式アカウントからユーザーにメッセージを送ったり ユーザーからのメッセージをWebhookで受け取ったりなど いろいろできるMessaging API https://developers.line.biz/ja/docs/messaging-api/overview/
35. 好きなテキストを⼊⼒して使える メッセージスタンプ https://creator-mag-ja.line.me/archives/1077517778.html
36. https://developers.line.biz/ja/news/2021/11/09/messaging-api-update/
37. メッセージスタンプを 説明すべきか 説明せざるべきか︖
38. もっと⼿前の スタンプとは何か から説明すべきか︖
39. いちいち⽤語を解説していたら 説明が⻑くなってしまう… でも⽤語説明しないと 分からない⼈がいるかも…
40. https://developers.line.biz/ja/news/2021/11/09/messaging-api-update/ ⽤語集ツールチップ
41. https://developers.line.biz/ja/glossary/ LINE Developersサイトには⽤語集がある
42. https://developers.line.biz/ja/news/2021/11/09/messaging-api-update/ ⽤語集ツールチップ
43. ⽤語説明が⼀箇所で済むし 必要ない⼈には邪魔にならない いいとこ取りな ⽤語集ツールチップ
44. ⽤語集ツールチップの裏側
45. VuePress
46. 注釈が書きたい︕ コードサンプルを タブで表⽰したい︕
47. VuePressはVue.jsで書かれているので マークダウンの機能を Vue.jsコンポーネントで 拡張できる
48. ⽤語集のページにリンクを貼るだけ
49. config.js（の⼀部）
50. <a href=“glossary/#message-sticker”> ↓ <a href=“glossary/#message-sticker” class=“glossary-tooltip”>
51. GlossaryTooltip.vue（の⼀部）
52. GlossaryTooltip.vue（の⼀部）
53. 説明すべきか 説明せざるべきか︖
54. 今⽇のセッション︓ ⽤語説明の悩みを マークダウンの機能拡張で解決した話
55. Developer Content Team
56. https://linecorp.com/ja/career/position/806
57. https://linecorp.com/ja/pr/news/ja/2021/3912
58. 1: ⽤語説明の悩みを マークダウンの機能拡張で解決した話 2: 伝わる⽂章を考えるために 〜テクニック以外に⼤切なことは︖〜 3: Questions and Answers 20th January 2022 19:00-21:00 LINE Technical Writing Meetup vol. 9
59. 1: ⽤語説明の悩みを マークダウンの機能拡張で解決した話 2: 伝わる⽂章を考えるために 〜テクニック以外に⼤切なことは︖〜 3: Questions and Answers 20th January 2022 19:00-21:00 LINE Technical Writing Meetup vol. 9
60. このイベントのアーカイブ動画は YouTubeでご覧いただけます https://youtube.com/playlist? list=PL80ip6bOwQsIfO757li02S42XDdWdnmED
61. 次回のLINE Technical Writing Meetupは 2⽉10⽇(⽊) 19:00に開催決定 https://line.connpass.com/event/236274