Skip to content

api_documentation.md

Latest commit

 

History

History
130 lines (90 loc) · 5.17 KB

api_documentation.md

File metadata and controls

130 lines (90 loc) · 5.17 KB

API Documentation

  • Reference
  • Concepts
  • Tasks

Here are the short, clear, correct answers for your APIsec course documentation quiz:

  1. What’s the difference between reference docs and concept docs? Answer: Reference docs are a round up API specs, list of supported data types, system requirements, etc. whereas concept docs refer to generic ideas covered briefly.

  2. What’s a good example of a Task doc? Answer: Documentation showing what the API is good at doing.

  3. Who benefits from good documentation? Answer: 3rd party partners, Developers, End consumers.

  4. What are Zombie APIs? Answer: Undocumented, unmaintained APIs that become unmonitored attack vectors.

  5. What does API sprawl refer to? Answer: API sprawl occurs when APIs are managed by different teams in the same org without visibility into what each team is working on.

  6. How can bad documentation or lack thereof cause security issues? Answer: Bad, poorly maintained, and/or non-existent documentation is an increased risk for security exposures because you need solid documentation of your APIs to maintain standardization and expose inconsistencies.

  7. What does shared leverage refer to when it comes to good documentation? Answer: Teams with visibility to existing and upcoming APIs, increase collaboration rather than duplicated functionality and wasted effort.

  8. Who typically writes documentation? Answer: Combination of Developers, Technical Writers, Product Managers.

  9. Why are developers NOT always the best documentation writers? Answer: Developers are not always good at thinking like consumers.

  10. What is one pro of having a Product Manager write your documentation? Answer: They provide a customer-centric perspective that can be effective in producing a more effective developer experience.

Good Documents for Security

Security, Governance & Partnerships

Business Impact of API Documentation answers:

Here are the correct, concise answers for those questions:

  1. Should you run your docs through a security review? Answer: Yes

  2. Bad, poorly maintained, and/or non-existent documentation is an _____ for security exposures. Answer: increased risk

  3. One weapon in your repository can be a security-style guide. This will help you: Answer: automate the enforcement of data formats or endpoint naming conventions utilize an enforceable security ruleset to dramatically fortify your defenses against data theft and resource exploits

  4. What’s one resource you can use to help maintain consistency and standardization in your documentation? Answer: Style Guides

  5. Why does good documentation matter to potential partners? Answer: It creates better brand affinity It helps scale your API It increases API adoption

  6. When letting devs test your documentation, what are the two most important steps to keep in mind? Answer: Any friction points & auth issues

  7. What’s another great tip to take advantage of when writing good documentation? Answer: Let your devs try it out before you publish it

Write Documents

  1. What is the prerequisite to generating any meaningful documentation? Answer: An OpenAPI document

  2. What companies were used as examples of great documentation in this module? Answer: Twilio and Stripe

  3. What are the benefits of using a documentation generator? Answer: Increased accuracy and less time to market The ability to quickly create an initial reference to share The ability to update documentation easily when the API changes

Documentation Tools & Techniques

Here are the correct answers for this set:

  1. What is one pro of using a Spec-based method to documentation? Answer: Either Design-first minimizes duplicated effort or it creates earlier feedback loops

  2. What are some documentation tools you can use to search for public documentation?
    Answer: Stoplight
    Swaggerhub
    Readme
    Redocly

  3. Which of these are techniques you can apply to your documentation writing? Answer: A code annotations approach A Spec-based approach A bespoke approach

Best Practice Documentation

Here are the correct answers for this set:

  1. What are some ways you can improve your documentation in the future? Answer: Use inclusive language Incorporate multimedia in the docs Create interactive docs, not just static ones

  2. How can you make your docs more accessible? Answer: Ensure your API documentation is usable by screen readers Ensure that colors, images, and tables also include labels and alt text Ensure that your documentation includes white space for easy scanning and navigation

  3. Which is better: static or interactive docs Answer: Interactive, since try-it-now consoles, examples, and live sandboxes usually improve comprehension and adoption.

  4. Are you ready to write amazing documentation? Answer: ABSOLUTELY