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

How to create the API document from real API and localization

How to create the API document from real API and localization

This deck is used API the Docs London 2018.

https://apithedocs.org/london2018

4cafe6a1c6287d64d7252279eeeffa94?s=128

Atsushi Nakatsugawa

November 09, 2018
Tweet

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 3FUVSOJUFNT:PVDBOTFBSDIJUFNTXJUIRVFSZ ঎඼Λऔಘ͠·͢ɻݕࡧ৚݅ΛࢦఆͰ͖· ͢ɻ 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