Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Engineer Stunning (API) documentation

18 views

Published on

Many of us have heard about Docs As Code. Applying the same tooling and delivery CI/CD (Continuous Integration and Continuous Delivery) pipelines as developers to improve the quality of (API) documentation sounds nifty. We’ll take a look at the philosophy, best practices and how to get started.

Published in: Technology
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download Full EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download Full doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THIS can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THIS is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THIS Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THIS the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THIS Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download Full EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download Full doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THIS can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THIS is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THIS Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THIS the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THIS Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

Engineer Stunning (API) documentation

  1. 1. 1 Engineer stunning (API) documentation Docs As Code Sven Strack • @der_sven_ • DocOps Engineer @ PRONOVIX
  2. 2. 2 WELCOME
  3. 3. ABOUT Docs As Code Building, maintaining and continually improving (API) documentation by doing Docs As Code the DocOps way.
  4. 4. OVERVIEW 4 Agenda ➔ Introduction to Docs As Code ➔ Advantages of QA testing of API and related documentation ➔ Start local ➔ Use CI/CD, too
  5. 5. DEFINITION 5 Stunning stun·ning | ˈstə-niŋ : strikingly impressive especially in beauty or excellence It’s about ALL aspects of (API) documentation ➔ Appealing appearance ➔ Content structure ➔ Clearity ➔ Grammar ➔ SEO ➔ Accessible
  6. 6. Docs As Code
  7. 7. DOCS AS CODE 7 Introduction Applying the Docs As Code method assumes that you use the same tooling for writing documentation which you use for working on your code. In the same manner that code editors are configured with plugins for reporting coding style violations, you can configure your code editor with plugins that report inconsistencies with your company's editorial and content style guides. Depending on your documentation, these could be plugins for checking the consistency of your markup language and your editorial style-guide, like the use of US or UK English, the style of headings, the length of documents and many more.
  8. 8. DOCS AS CODE Why should I use it ➔ Consistent, tested APIs and documentation can help your product and your development cycle. ➔ Consistency is a important trust signal. ➔ Writing your documentation according to a defined standard reflecting your product and company is good for SEO.
  9. 9. 9 ATTENTION
  10. 10. Word of advice Avoid disaster! ➔ Working with Docs As Code can help you improve the quality and speed up the publication process, but it also has a learning curve. ➔ A deeper knowledge of engineering tools, workflows and a solid base and understanding of security is necessary. DOCS AS CODE
  11. 11. DOCS AS CODE Word of advice ➔ Make sure that all your tests are working, that you can trust the results, and that your infrastructure is well configured and secure. ➔ Developers, DevOps, and your Site Reliability (SRE) teams can assist you to make sure everything is set up properly. ➔ These are critical to quality, you do want to make sure that you configure your git repositories properly, set permissions, etc.
  12. 12. DOCS AS CODE Content Strategy and Design 12 ➔ Message architecture ➔ Editorial Style Guidelines ➔ Markup Style Guidelines ➔ Objectives and key results ➔ “ROT” analysis (Redundant, Outdated, Trivial) “If you don’t know what you want or need to communicate, how will you know if you succeed?” This is where content strategy and design can help.
  13. 13. DOCS AS CODE Core Subjects Docs As Code breaks down into five points: ➔ Content strategy ➔ Editorial style guidelines ➔ Content analytics ➔ Automated testing ➔ Deploying (publishing)
  14. 14. WORKFLOW 14 Docs As Code Write Text Editor Style Guide Commit VCS Version Control System CI/CD Run Q&A Checks Deploy Trigger Deploy Request Review Pull Request Merge New Version Online
  15. 15. 15 WORKFLOW
  16. 16. Quality Assurance
  17. 17. QUALITY ASSURANCE API and Documentation Quality Assurance Quality assurance (QA) is the process of verifying whether a product meets the required specifications and customer expectations
  18. 18. API and Documentation Quality Assurance Why is QA important? ➔ Product documentation is an important marketing asset for promoting both your product and your organization. ➔ Good documentation helps you to satisfy your customers. ➔ Happy clients, it also means less support work and thus, more time for other projects. It will also save your company money. ➔ Good documentation gets people to jump into your project quicker ➔ Consistent docs are a trust signal. QUALITY ASSURANCE
  19. 19. DO NOT FORGET Friendly reminder A deeper knowledge of engineering tools, workflows and a solid base and understanding of security is absolutely necessary to set up a Docs As Code way of working. ➔ Protect your branches ➔ Validate all your checks according to best practices ➔ Keep checks “simple” and “easy” to adjust ➔ Start small ➔ Make your checks depending on each other 19
  20. 20. 20 Where to start Define your goals A good first step is to determine what you want to achieve. ➔ Defining a style guide ➔ User stories ➔ Analytics QUALITY ASSURANCE
  21. 21. Quality Assurance _> local
  22. 22. QA LOCAL 22 Quality Assurance starts locally Remember
  23. 23. LOCAL QUALITY ASSURANCE 23
  24. 24. LOCAL QUALITY ASSURANCE 24 Almost stunning
  25. 25. Quality Assurance _> with CI/CD
  26. 26. QA with CI/CD Continuous Integration GitLab – AWS Pipeline – GoCD – Semaphore – and many more
  27. 27. CONTINUOUS INTEGRATION 27 Automated QA Checks CircleCI
  28. 28. 28 CONTINUOUS INTEGRATION Automated QA Checks GitLab
  29. 29. 29 CONTINUOUS INTEGRATION Automated QA Checks Drone CI
  30. 30. 30 CONTINUOUS INTEGRATION Automated QA Checks GitHub Action
  31. 31. 31 CONTINUOUS INTEGRATION Automated QA Checks GitHub Action
  32. 32. RECAP 32 Key Takeaways ➔ Know what you want to check ➔ Start early ➔ Start small ➔ Start local ➔ Make sure checks a valid and working ➔ Work secure ➔ Take your time ➔ Reevaluate
  33. 33. QUESTIONS 33
  34. 34. 34 Your Host for Today Sven Strack DocOps Engineer @Pronovix ABOUT ME
  35. 35. Sven Strack DocOps Engineer sven.strack@pronovix.com
  36. 36. Developer portal mailing list bit.ly/devportals 36Pronovix confidential and proprietary

×