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


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
  • Login to see the comments

  • 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
  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
  36. 36. Developer portal mailing list 36Pronovix confidential and proprietary