Specialized Technical Writing Team to Provide Documentation for LINE Developers

Yoshiko Horikoshi
LINE / Developer Content team / Technical Writer
Roman Lossa
LINE / Developer Content team / Frontend Engineer

https://linedevday.linecorp.com/2021/ja/sessions/148
https://linedevday.linecorp.com/2021/en/sessions/148
https://linedevday.linecorp.com/2021/ko/sessions/148

Transcript

2. Yoshiko Horikoshi @mochikoAsTech Yoshiko Horikoshi is a Technical Writer in charge of documents of the LINE Developers site (https:// developers.line.biz/). She used to work as an infrastructure engineer at a web design company. At Techbookfest, several books about infrastructure were published in her name, such as "Let's start DNS 2nd Edition". She also hosts the LINE Technical Writing Meetup, a meetup for engineers on the topic of technical writing. Cats are her absolute favorite animal.
3. Roman Lossa - Frontend engineer - In charge of developers.line.biz - Made in Germany - Moved to Japan 6 years ago - Loves Vue.js - Loves YouTube
4. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
5. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
6. Do you know what a Technical Writer is? I know very well Yes I've heard the term before Kind of Technical what? No
7. The difference between having or not having technical writers What does a Technical Writer do?
8. Docs written by developers e.g. Messaging API's rich menu alias docs
9. Docs written by Technical Writers e.g. Messaging API's rich menu alias docs
10. Docs written by Technical Writers e.g. Messaging API's rich menu alias docs
11. Docs written by Technical Writers e.g. Messaging API's rich menu alias docs
12. What is the role of a Technical Writer? In general: A Technical Writer is a person who writes instruction manuals. LINE's technical writers are responsible for writing technical documentation for external developers. In LINE:
13. Adding a LINE Login button to your website You want to add a LINE Login button to your website. But how?
14. LINE's Technical Writers write LINE API docs for developers CLOVA Developer Center β https://clova-developers.line.biz/ LINE Developers site https://developers.line.biz/
15. Dedicated Technical Writing Team 6 Technical Writers and 1 Developer
16. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
17. How are the LINE API docs written? Yoshiko Horikoshi LINE Corporation / Developer Content Team
18. Docs are available in English and Japanese Some documents are also available in Chinese
19. Get specs from developers, write docs and translate
20. We use VSCode to write docs in markdown With automatic grammar checking using linters like Vale and textlint
21. Run on localhost and check
22. Push to git, create pull request
23. Automatic build, links, and grammar checks
24. Review the docs on Sandbox Deploy a build of each git branch to check the changes on the actual site
25. Get LGTM, merge into master, and have Jenkins do the deployment
26. Dev environments / servers There’s a few Beta (internal, beta check) Sandbox (internal, all WIP builds) RC (internal, final check) Local dev server Production (public)
27. We all rejoice when a docs release is done! We are releasing about 25 updates per month
28. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
29. Yoshiko Horikoshi LINE Corporation / Developer Content Team The benefits of having a technical writing team
30. Docs written by Technical Writers e.g. LIFF-to-LIFF transition docs
31. Docs written by Technical Writers e.g. Error notification docs
32. Docs are important! - How to have your product being used: - High quality product - High quality docs - Ability to develop != ability to write - By having a dedicated team of technical writers, developers can focus on development!
33. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
34. Who is suited to become a Technical Writer? Yoshiko Horikoshi LINE Corporation / Developer Content Team
35. Skills required for Technical Writers in LINE Who is suited to become a Technical Writer? Technical skills to understand the specs Reading and writing skills in Japanese and English Writing skills to write easy- to-understand docs
36. We can't write easy-to-understand docs without understanding the technology Messaging API's Flex Message docs We need to understand CSS Flexbox LINE Login docs We need to understand technologies such as OAuth
37. There are many products in LINE, so Technical Writers must be actively learning about various technologies
38. No Technical Writer? No problem! - IT companies are hiring - Can’t find Technical Writers? Ask your devs! - There are devs writing blogs or books!
39. Next: The Engineer's perspective (Roman)
40. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
41. The unicorn in disguise Why you should assign an engineer to your writing team
42. Writing is hard That’s why we have professionals - Writing is the most important part to a good documentation - There’s a reason we have professional technical writers - There’s A LOT to write about - BUT: Writing is only 1 part of the UX
43. The complete UX There’s more than writing - Also: User-friendly site providing the contents - Well written documentation UX Documentation Website
44. Delivering a user-friendly site (1) Features, features, features… Multi-language support UI that supports English, Japanese, and Chinese Blazing fast through SPA (VuePress) Fast navigation through site
45. Delivering a user-friendly site (2) Features, features, features… Feedback form Know what our users think Full text search Making all the contents searchable (Available in English and Japanese)
46. Delivering a user-friendly site (3) Features, features, features… Interactive News filtering Find the news you’re looking for Interactive API reference Collapsable sections, code samples, API playground…
47. What to ask a professional Let’s be appropriate
48. What to ask a professional No sushi at your Italian restaurant ⁉ “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
49. What to ask a professional No developing from your writers Website dev?! “Twemoji” ©Twitter, Inc and other contributors (Licensed under CC-BY 4.0) https://twemoji.twitter.com/
50. …Houston, we need an engineer!
51. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
52. Supporting the writers Focus on your profession
53. - Provide an easy-to-use platform to create contents (documentation) - Everyday support 2. (Internal) Technical Writers 1. (External) Outside devs - Provide an easy-to-use site for external users (developers) My role as an engineer I serve two types of users
54. Platform for writers Easy-to-use environment is king - Easy local setup - git clone npm install ./run.sh
55. Platform for writers Easy-to-use environment is king - Easy local setup - git clone npm install ./run.sh
56. Platform for writers Easy-to-use environment is king - Write markdown! - Easy local setup - git clone npm install ./run.sh
57. More than markdown When basic functionality is not enough
58. - Markdown support - Localization support - Vue.js - SPA (fast!) - Markdown extensions via Vue.js components Core system: VuePress vuepress.vuejs.org
59. API reference Markdown extensions - Example 1
60. Markdown extensions - Example 1 API reference Not supported by plain markdown: - Two column layout - Parameter table layout - Code samples with tabs
61. Two-column layout <ReferenceWithCode> Markdown extensions - Example 1 API reference
62. <ReferenceContent>, <ReferenceCode> Markdown extensions - Example 1 API reference
63. <ReferenceContent>, <ReferenceCode> Markdown extensions - Example 1 API reference
64. <ReferenceContent>, <ReferenceCode> Markdown extensions - Example 1 API reference
65. Tabbed code samples Markdown extensions - Example 1 API reference
66. Tabbed code samples Markdown extensions - Example 1 API reference
67. Messaging API: Stickers Markdown extensions - Example 2
68. Markdown extensions - Example 2 Messaging API: Stickers
69. Markdown extensions - Example 2 Messaging API: Stickers
70. BEFORE: PDF AFTER: Interactive UI Markdown extensions - Example 2 Messaging API: Stickers
71. 1. Retrieve internal Messaging API data 2. Extract sticker package data 3. Integrate into interactive UI Markdown extensions - Example 2 Messaging API: Stickers
72. UI source code (developer’s view) Markdown (writer’s view) Markdown extensions - Example 2 Messaging API: Stickers
73. UI source code (developer’s view) Markdown (writer’s view) Markdown extensions - Example 2 Messaging API: Stickers
74. Markdown (writer’s view)
75. Markdown (writer’s view)
76. From engineering to dev ops to tech support Everyday Support
77. Sudden feature requests Deploy troubleshooting Handling CI/CD system troubles Pull request checks System updates Sandbox and local dev server support Everyday Support From engineering to dev ops to tech support 㱺 Impossible without dedicated dev!
78. Benefits for me There’s many! Broadening my horizon Working independently Great responsibility
79. Agenda - About this session - Technical writer's part (Horikoshi) - What does a Technical Writer do? - How are the LINE API docs written? - The benefits of having a technical writing team - Who is suited to become a Technical Writer? - Engineer's part (Roman) - Why you should assign an engineer to your writing team - Supporting the writers - Conclusion (Horikoshi)
80. Conclusion
81. Conclusion Happiness is all around To make your product usable (to external devs), docs (and writers) are important! Having an engineer is good for your technical writing team Having a technical writing team is good for you
82. We are hiring Technical Writers https://linecorp.com/ja/career/position/806
83. LINE Technical Writing Meetup https://www.youtube.com/playlist?list=PL80ip6bOwQsIfO757li02S42XDdWdnmED
84. Thank you