$30 off During Our Annual Pro Sale. View Details »

Specialized Technical Writing Team to Provide Documentation for LINE Developers

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

LINE DEVDAY 2021
PRO

November 11, 2021
Tweet

More Decks by LINE DEVDAY 2021

Other Decks in Technology

Transcript

  1. None
  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