Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

November 11, 2021
Tweet

More Decks by LINE DEVDAY 2021

Other Decks in Technology

Transcript

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

    View full-size slide

  2. Roman Lossa
    - Frontend engineer
    - In charge of developers.line.biz
    - Made in Germany
    - Moved to Japan 6 years ago
    - Loves Vue.js
    - Loves YouTube

    View full-size slide

  3. 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)

    View full-size slide

  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)

    View full-size slide

  5. Do you know what a Technical Writer is?
    I know very well
    Yes
    I've heard the term before
    Kind of
    Technical what?
    No

    View full-size slide

  6. The difference between having or not having technical writers
    What does a
    Technical Writer do?

    View full-size slide

  7. Docs written by developers
    e.g. Messaging API's rich menu alias docs

    View full-size slide

  8. Docs written by Technical Writers
    e.g. Messaging API's rich menu alias docs

    View full-size slide

  9. Docs written by Technical Writers
    e.g. Messaging API's rich menu alias docs

    View full-size slide

  10. Docs written by Technical Writers
    e.g. Messaging API's rich menu alias docs

    View full-size slide

  11. 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:

    View full-size slide

  12. Adding a LINE Login button to your website
    You want to add a LINE Login button
    to your website.
    But how?

    View full-size slide

  13. 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/

    View full-size slide

  14. Dedicated Technical Writing Team
    6 Technical Writers and 1 Developer

    View full-size slide

  15. 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)

    View full-size slide

  16. How are the LINE API docs
    written?
    Yoshiko Horikoshi
    LINE Corporation / Developer Content Team

    View full-size slide

  17. Docs are available in English and Japanese
    Some documents are also available in Chinese

    View full-size slide

  18. Get specs from developers,
    write docs and translate

    View full-size slide

  19. We use VSCode to write docs in markdown
    With automatic grammar checking using linters like Vale and textlint

    View full-size slide

  20. Run on localhost and check

    View full-size slide

  21. Push to git, create pull request

    View full-size slide

  22. Automatic build, links, and grammar checks

    View full-size slide

  23. Review the docs on Sandbox
    Deploy a build of each git branch to check the changes on the actual site

    View full-size slide

  24. Get LGTM, merge into master,
    and have Jenkins do the deployment

    View full-size slide

  25. 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)

    View full-size slide

  26. We all rejoice when a docs release is done!
    We are releasing about 25 updates per month

    View full-size slide

  27. 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)

    View full-size slide

  28. Yoshiko Horikoshi
    LINE Corporation / Developer Content Team
    The benefits of having a
    technical writing team

    View full-size slide

  29. Docs written by Technical Writers
    e.g. LIFF-to-LIFF transition docs

    View full-size slide

  30. Docs written by Technical Writers
    e.g. Error notification docs

    View full-size slide

  31. 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!

    View full-size slide

  32. 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)

    View full-size slide

  33. Who is suited to become a
    Technical Writer?
    Yoshiko Horikoshi
    LINE Corporation / Developer Content Team

    View full-size slide

  34. 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

    View full-size slide

  35. 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

    View full-size slide

  36. There are many products in LINE,
    so Technical Writers must be actively
    learning about various technologies

    View full-size slide

  37. No Technical Writer? No problem!
    - IT companies are hiring
    - Can’t find Technical Writers? Ask your devs!
    - There are devs writing blogs or books!

    View full-size slide

  38. Next: The Engineer's perspective (Roman)

    View full-size slide

  39. 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)

    View full-size slide

  40. The unicorn in disguise
    Why you should assign an
    engineer to your writing team

    View full-size slide

  41. 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

    View full-size slide

  42. The complete UX
    There’s more than writing
    - Also: User-friendly site providing the contents
    - Well written documentation
    UX
    Documentation
    Website

    View full-size slide

  43. 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

    View full-size slide

  44. 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)

    View full-size slide

  45. 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…

    View full-size slide

  46. What to ask a professional
    Let’s be appropriate

    View full-size slide

  47. 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/

    View full-size slide

  48. 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/

    View full-size slide

  49. …Houston, we need
    an engineer!

    View full-size slide

  50. 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)

    View full-size slide

  51. Supporting the writers
    Focus on your profession

    View full-size slide

  52. - 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

    View full-size slide

  53. Platform for writers
    Easy-to-use environment is king
    - Easy local setup
    - git clone
    npm install
    ./run.sh

    View full-size slide

  54. Platform for writers
    Easy-to-use environment is king
    - Easy local setup
    - git clone
    npm install
    ./run.sh

    View full-size slide

  55. Platform for writers
    Easy-to-use environment is king
    - Write markdown!
    - Easy local setup
    - git clone
    npm install
    ./run.sh

    View full-size slide

  56. More than markdown
    When basic functionality is not enough

    View full-size slide

  57. - Markdown support
    - Localization support
    - Vue.js
    - SPA (fast!)
    - Markdown extensions via
    Vue.js components
    Core system: VuePress
    vuepress.vuejs.org

    View full-size slide

  58. API reference
    Markdown extensions -
    Example 1

    View full-size slide

  59. Markdown extensions - Example 1
    API reference
    Not supported by plain
    markdown:
    - Two column layout
    - Parameter table layout
    - Code samples with tabs

    View full-size slide

  60. Two-column layout
    Markdown extensions - Example 1
    API reference

    View full-size slide

  61. ,
    Markdown extensions - Example 1
    API reference

    View full-size slide

  62. ,
    Markdown extensions - Example 1
    API reference

    View full-size slide

  63. ,
    Markdown extensions - Example 1
    API reference

    View full-size slide

  64. Tabbed code samples
    Markdown extensions - Example 1
    API reference

    View full-size slide

  65. Tabbed code samples
    Markdown extensions - Example 1
    API reference

    View full-size slide

  66. Messaging API: Stickers
    Markdown extensions -
    Example 2

    View full-size slide

  67. Markdown extensions - Example 2
    Messaging API: Stickers

    View full-size slide

  68. Markdown extensions - Example 2
    Messaging API: Stickers

    View full-size slide

  69. BEFORE: PDF AFTER: Interactive UI
    Markdown extensions - Example 2
    Messaging API: Stickers

    View full-size slide

  70. 1. Retrieve internal Messaging API data
    2. Extract sticker package data
    3. Integrate into interactive UI
    Markdown extensions - Example 2
    Messaging API: Stickers

    View full-size slide

  71. UI source code (developer’s view) Markdown (writer’s view)
    Markdown extensions - Example 2
    Messaging API: Stickers

    View full-size slide

  72. UI source code (developer’s view) Markdown (writer’s view)
    Markdown extensions - Example 2
    Messaging API: Stickers

    View full-size slide

  73. Markdown (writer’s view)

    View full-size slide

  74. Markdown (writer’s view)

    View full-size slide

  75. From engineering to dev ops to tech support
    Everyday Support

    View full-size slide

  76. 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!

    View full-size slide

  77. Benefits for me
    There’s many!
    Broadening my horizon
    Working independently
    Great responsibility

    View full-size slide

  78. 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)

    View full-size slide

  79. 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

    View full-size slide

  80. We are hiring Technical Writers
    https://linecorp.com/ja/career/position/806

    View full-size slide

  81. LINE Technical Writing Meetup
    https://www.youtube.com/playlist?list=PL80ip6bOwQsIfO757li02S42XDdWdnmED

    View full-size slide