Specialized Technical Writing Team to Provide Documentation for LINE Developers

Slide 1

Slide 1 text

No content

Slide 2

Slide 2 text

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.

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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)

Slide 5

Slide 5 text

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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:

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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/

Slide 15

Slide 15 text

Dedicated Technical Writing Team 6 Technical Writers and 1 Developer

Slide 16

Slide 16 text

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

Get specs from developers, write docs and translate

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

Run on localhost and check

Slide 22

Slide 22 text

Push to git, create pull request

Slide 23

Slide 23 text

Automatic build, links, and grammar checks

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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)

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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!

Slide 33

Slide 33 text

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

Next: The Engineer's perspective (Roman)

Slide 40

Slide 40 text

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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)

Slide 46

Slide 46 text

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…

Slide 47

Slide 47 text

What to ask a professional Let’s be appropriate

Slide 48

Slide 48 text

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/

Slide 49

Slide 49 text

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/

Slide 50

Slide 50 text

…Houston, we need an engineer!

Slide 51

Slide 51 text

Slide 52

Slide 52 text

Supporting the writers Focus on your profession

Slide 53

Slide 53 text

- 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

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

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

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

More than markdown When basic functionality is not enough

Slide 58

Slide 58 text

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

Slide 59

Slide 59 text

API reference Markdown extensions - Example 1

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

Two-column layout Markdown extensions - Example 1 API reference

Slide 62

Slide 62 text

, Markdown extensions - Example 1 API reference

Slide 63

Slide 63 text

, Markdown extensions - Example 1 API reference

Slide 64

Slide 64 text

, Markdown extensions - Example 1 API reference

Slide 65

Slide 65 text

Tabbed code samples Markdown extensions - Example 1 API reference

Slide 66

Slide 66 text

Tabbed code samples Markdown extensions - Example 1 API reference

Slide 67

Slide 67 text

Messaging API: Stickers Markdown extensions - Example 2

Slide 68

Slide 68 text

Markdown extensions - Example 2 Messaging API: Stickers

Slide 69

Slide 69 text

Markdown extensions - Example 2 Messaging API: Stickers

Slide 70

Slide 70 text

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

Slide 71

Slide 71 text

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

Slide 72

Slide 72 text

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

Slide 73

Slide 73 text

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

Slide 74

Slide 74 text

Markdown (writer’s view)

Slide 75

Slide 75 text

Markdown (writer’s view)

Slide 76

Slide 76 text

From engineering to dev ops to tech support Everyday Support

Slide 77

Slide 77 text

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!

Slide 78

Slide 78 text

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

Slide 79

Slide 79 text

Slide 80

Slide 80 text

Conclusion

Slide 81

Slide 81 text

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

Slide 82

Slide 82 text

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

Slide 83

Slide 83 text

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

Slide 84

Slide 84 text

Thank you