How to create the API document from real API and localization

This deck is used API the Docs London 2018.

https://apithedocs.org/london2018

Transcript

1. PAGE # MOONGIFT / 29 DAY 2018/11/09 How to create the API document from real API and localization 1
2. PAGE # MOONGIFT / 29 DAY 2018/11/09 Who am I? 2 @goofmint fb.me/goofmint Atsushi Nakatsugawa CEO at MOONGIFT Evangelist Community Organizer
3. PAGE # MOONGIFT / 29 DAY 2018/11/09 About this talk • It is based on my experience • I will share with you how to improving document maintenance environment • It’s not high level and no smart, but it’s realistic 3
4. PAGE DAY 2018/11/09 # MOONGIFT / 29 First Situation 4
5. PAGE # MOONGIFT / 29 DAY 2018/11/09 First situation • API document is managed by GitHub Wiki • Minimum quality, for their workers • Ineffective maintenance document 5
6. PAGE # MOONGIFT / 29 DAY 2018/11/09 GitHub Wiki • Updating content on web browser and supporting version management. • Dividing code and document. Don’t support pull request workflow. • Don’t support localization. 6
7. PAGE # MOONGIFT / 29 DAY 2018/11/09 Un documentation API • Wiki didn’t cover everything and every update. • Checking is very hard job that what is collect or not. • Halfway document disturbs my job. 7 I've decided creating document from zero.
8. PAGE DAY 2018/11/09 # MOONGIFT / 29 Specifications 8
9. PAGE # MOONGIFT / 29 DAY 2018/11/09 Specifications • Support # and $ • Document has API, tutorials, usage and more • Easy maintenance 9
10. PAGE # MOONGIFT / 29 DAY 2018/11/09 Localization • Make misunderstanding by no native language • English speaking rate is too low in Japan (12%) • Update document cost is very high (English to Japanese) 10
11. PAGE # MOONGIFT / 29 DAY 2018/11/09 Translating is not localization • Structure of sentence is completely different • Many times, English needs longer sentence than Japanese • Machine translation is weird 11
12. PAGE # MOONGIFT / 29 DAY 2018/11/09 Translating is not localization • Structure of sentence is completely different • Many times, English needs longer sentence than Japanese • Machine translation is weird 12
13. PAGE # MOONGIFT / 29 DAY 2018/11/09 Document in Code • Connecting code and document • Too much comment in code for documentation • Programmer is NOT necessarily able to write high readability document • Most document generators don’t support i18n. 13 desc 'Returns your public timeline.' do summary 'summary' detail 'more details' params API::Entities::Status.documentation success API::Entities::Entity failure [[401, 'Unauthorized', 'Entities::Error']] named 'My named route' headers XAuthToken: { description: 'Validates your identity', required: true }, XOptionalHeader: { description: 'Not really needed', required: false } hidden false deprecated false is_array true nickname 'nickname' produces ['application/json'] consumes ['application/json'] tags ['tag1', 'tag2'] end get :public_timeline do Status.limit(20) end
14. PAGE # MOONGIFT / 29 DAY 2018/11/09 Architecture 14 API Swagger GetText Markdown Static Site Generator
15. PAGE DAY 2018/11/09 # MOONGIFT / 29 Works 15
16. PAGE # MOONGIFT / 29 DAY 2018/11/09 Architecture 16 API Swagger GetText Markdown Static Site Generator
17. PAGE # MOONGIFT / 29 DAY 2018/11/09 Real API to Swagger • There is kitchen sink app • Developer can learn how to use JavaScript SDK & API 17
18. PAGE # MOONGIFT / 29 DAY 2018/11/09 Tool 1 : curlToSwagger • Chrome provides curl command in Devtools • Copy it • Parse it • Generate swagger document 18 https://github.com/goofmint/cURLtoSwagger
19. PAGE # MOONGIFT / 29 DAY 2018/11/09 Tool 1 : curlToSwagger • Chrome provides curl command in Devtools • Copy it • Parse it • Generate swagger document 19 https://github.com/goofmint/cURLtoSwagger curl ‘https://samples.openweathermap.org/data/2.5/forecast? id=52...a1' \ -XGET \ -H 'Cookie: __utma=124); __utmt=1' \ -H 'Accept: text...q=0.8’ \ -H 'Accept-Encoding: gzip, deflate' \ -H 'Upgrade-Insecure-Requests: 1' \ -H 'Host: samples.openweathermap.org' \ -H 'User-Agent: Mozilla...15’ \ -H 'Accept-Language: ja-jp' \ -H 'DNT: 1' \ -H 'Connection: keep-alive'
20. PAGE # MOONGIFT / 29 DAY 2018/11/09 Tool 1 : curlToSwagger • Chrome provides curl command in Devtools • Copy it • Parse it • Generate swagger document 20 https://github.com/goofmint/cURLtoSwagger
21. PAGE # MOONGIFT / 29 DAY 2018/11/09 Tool 1 : curlToSwagger • Chrome provides curl command in Devtools • Copy it • Parse it • Generate swagger document 21 https://github.com/goofmint/cURLtoSwagger
22. PAGE # MOONGIFT / 29 DAY 2018/11/09 Tool 1 : curlToSwagger • Chrome provides curl command in Devtools • Copy it • Parse it • Generate swagger document 22 https://github.com/goofmint/cURLtoSwagger
23. PAGE # MOONGIFT / 29 DAY 2018/11/09 Architecture 23 API Swagger GetText Markdown Static Site Generator
24. PAGE # MOONGIFT / 29 DAY 2018/11/09 Tool 2 : Swagger2Markdown • Parse swagger file • Pick up each sentences • Make po file for translating (ja.po or en.po) • Update po file • Create English and Japanese Markdown files 24 https://github.com/goofmint/swagger2markdown # vibration.md msgid "Vibration API" msgstr "Vibration API" # vibration.md msgid "### Basic specifications" msgstr "### Basic specifications" # vibration.md msgid "API Path" msgstr "API Path" # vibration.md msgid ": /gotapi/vibration/vibrate" msgstr ": /gotapi/vibration/vibrate" # vibration.md msgid "Method" msgstr "Method"
25. PAGE # MOONGIFT / 29 DAY 2018/11/09 Tool 2 : Swagger2Markdown • Parse swagger file • Pick up each sentences • Make po file for translating (ja.po or en.po) • Update po file • Create English and Japanese Markdown files 25 https://github.com/goofmint/swagger2markdown # vibration.md msgid "Vibration API" msgstr "όΠϒϨʔγϣϯ API" # vibration.md msgid "### Basic specifications" msgstr "### جຊ࢓༷" # vibration.md msgid "API Path" msgstr "APIύε" # vibration.md msgid ": /gotapi/vibration/vibrate" msgstr ": /gotapi/vibration/vibrate" # vibration.md msgid "Method" msgstr "ϝιου"
26. PAGE # MOONGIFT / 29 DAY 2018/11/09 Example 26 ,FZ &OHMJTI +BQBOFTF BQJJUFNTOBNF *UFN
    "1* ঎඼
    "1* BQJJUFNTTVNNBSZ 3FUVSO
    JUFNT
    :PV
    DBO
    TFBSDI
    JUFNT
    XJUI
    RVFSZ ঎඼Λऔಘ͠·͢ɻݕࡧ৚݅ΛࢦఆͰ͖· ͢ɻ BQJJUFNTDPVOUPOF \DPVOU^
    JUFN \DPVOU^
    ݸ BQJJUFNTDPVOUNPSF \DPVOU^
    JUFNT \DPVOU^
    ݸ
27. PAGE # MOONGIFT / 29 DAY 2018/11/09 Architecture 27 API Swagger GetText Markdown Static Site Generator
28. PAGE # MOONGIFT / 29 DAY 2018/11/09 Why Markdown? • Most swagger based document generators don’t support localization. • Many static site generators support Markdown format • We can add more contents like tutorials, getting started, SDK help and more! • We choose MkDocs for documentation. 28 https://www.mkdocs.org
29. PAGE DAY 2018/11/09 # MOONGIFT / 29 Conclusion 29
30. PAGE # MOONGIFT / 29 DAY 2018/11/09 API to Document • Document is not code • Too many comments are lower readability of code • Test code or kitchen sink is good tutorial for programmers • 1 correct code is more worth than 100 words 30
31. PAGE # MOONGIFT / 29 DAY 2018/11/09 Localization • It’s very important for non-native English speakers • It’s easy to create just one time • It’s difficult to update document immediately 31
32. PAGE # MOONGIFT / 29 DAY 2018/11/09 We are NOT hiring • We want your CFP of DevRelCon Tokyo 2019 • Meet at Tokyo on March 9th • Follow @DevRelConTokyo 32
33. PAGE # MOONGIFT / 29 DAY 2018/11/09 Thanks! & 33 @goofmint fb.me/goofmint