Engineer Stunning (API) documentation
0 likes176 views
The document discusses the 'docs as code' methodology for creating and maintaining API documentation, emphasizing its consistency, quality assurance, and the use of developer tools. It highlights the advantages of automating QA testing and integrating this process into CI/CD workflows to enhance documentation standards. The key components include content strategy, editorial guidelines, and quality control practices necessary for successful implementation.
Engineer Stunning (API) documentation
- 1. 1 Engineer stunning (API) documentation Docs As Code Sven Strack • @der_sven_ • DocOps Engineer @ PRONOVIX
- 2. 2 WELCOME
- 3. ABOUT Docs As Code Building, maintaining and continually improving (API) documentation by doing Docs As Code the DocOps way.
- 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. 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. Docs As Code
- 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. 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 ATTENTION
- 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. 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. 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. 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. 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 WORKFLOW
- 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. 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. 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 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. Quality Assurance _> local
- 22. QA LOCAL 22 Quality Assurance starts locally Remember
- 25. Quality Assurance _> with CI/CD
- 26. QA with CI/CD Continuous Integration GitLab – AWS Pipeline – GoCD – Semaphore – and many more
- 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. QUESTIONS 33
- 34. 34 Your Host for Today Sven Strack DocOps Engineer @Pronovix ABOUT ME
- 36. Developer portal mailing list bit.ly/devportals 36Pronovix confidential and proprietary