🥥API Documentation Best Practices

In simple terms, this is a human readable description of how developers will enable machines to communicate with each other. It's a mouthful, but this is my attempt to wrap up a few different things. One is documentation is for humans.

What types of documentation?

• Reference es basicamente la del tipo de doc que es para los desarrolladores, vemos a nivel muy tecnico todo de la doc para entender como funciona, como se integra y pasar a nuestro codigo integrandolo a la DOC.

Value Of Good Documentation:

Top 3 Reasons Documentation is Must-Have

• API Sprawl se refiere a cuando una organización tiene muchas APIs dispersas, mal organizadas, sin control ni visibilidad clara, lo cual genera caos. Es como tener un montón de puertas abiertas en una empresa… y no saber a dónde llevan ni quién las usa.

Top 2 Reasons Documentation is Nice-to-Have

Who writes the docs anyways?

Quiz:

Question 1
What’s the difference between reference docs and concept docs?
Concept docs are for feelings, references docs are for memes
Reference docs are for brief, generic ideas whereas concept docs cover list of supported data types, API specs, etc.
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
Correct answer.
Only technical writers use concept docs, all others use reference docs

Question 2
Whats a good example of a Task doc?
Documentation overviewing your house projects to-do list
Documentation showing what the API is good at doing
Correct answer.
Documentation explaining word definitions or industry jargon
None of the above

Question 3
Who benefits from good documentation?
3rd party partners
Developers
End consumers
All of the above
Correct answer.

Question 4
What are Zombie APIs?
Undocumented, unmaintained APIs that become unmonitored attack vectors
Correct answer.
APIs that you make during the month of October to Celebrate Halloween
APIs that never passed their security check
Fake APIs

Question 5
What does API sprawl refer to?
The ability of APIs to take over the world
API sprawl occurs when APIs are managed by different teams in the same org without visibility into what each team is working on
Correct answer.
Proliferation of APIs across every industry, making APIs an ‘everyone’ technology and not just a concept for technology companies
Y2K 2.0

Question 6
How can bad documentation or lack thereof cause security issues?
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
Correct answer.
No docs, less locks
Hackers hate documentation
Security team members will never want to work with the API Team if they don’t have things properly documented

Question 7
What does shared leverage refer to when it comes to good documentation?
If good documentation exists, it helps convince your community your API is worthwhile
Teams with visibility to existing and upcoming APIs, increase collaboration rather than duplicated functionality and wasted effort
Correct answer.
Automated options exist, but the only sure way is to establish a source of truth, is with the goal of good documentation: a definitive Developer Portal
If everyone splits up writing the documentation, they’ll all have shared leverage in how it’s used

Question 8
Who typically writes documentation?
Developers
Technical Writers
Product Managers
Some combination of the above
Correct answer.

Question 9
Why are developers NOT always the best documentation writers?
Developers won’t work with marketing to double check everything is brand complaint
Developers will focus too much on the nitty-gritty technical details
Developers are not always good at thinking like consumers
Correct answer.
Developers don’t know how to write, only code

Question 10
What is one pro of having a Product Manager write your documentation?
They provide a customer-centric perspective that can be effective in producing a more effective developer experience
Correct answer.
They understand the product best so they can probably explain it best
They’re super cool people
They’re more likely to be brand compliant

---

Good docs matter to security

• Con esto hacemos referencia a cual es el impacto positivo de documentation al negocio? to bussinesss flow →

Good docs matter for improved governance

governance (gobernanza) se refiere al conjunto de políticas, reglas, procesos y estándares que se aplican para asegurar que las APIs:

• Que sigan convenciones de nombres, estructuras de endpoints, versionado, buenas prácticas.

• Que incluyan autenticación, autorización, cifrado y manejo adecuado de errores.

• Que el ciclo de vida (creación, pruebas, despliegue, deprecación) esté bien gestionado.

Good docs matter for partnership

Quiz:

Question 1
Should you run your docs through a security review?
Yes
Correct answer.
No

Question 2
Bad, poorly maintained, and/or non-existent documentation is an _______ for security exposures.
decreased risk
increased risk
Correct answer.
excellent idea
none of the above

Question 3
One weapon in your repository can be a security-style guide. This will help you:
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
Both A&B
Correct answer.
Defend against all hackers, battle bot style

Question 4
What’s one resource you can use to help maintain consistency and standardization in your documentation?
Spellcheck
A really good writer
Style Guides
Correct answer.
A yearly review of all docs

Question 5
Why does good documentation matter to potential partners?
It creates better brand affinity
It helps scale your API
It increases API adoption
All of the above
Correct answer.

Question 6
When letting devs test your documentation, what are the two most important steps to keep in mind?
The documentation is visually pleasing & includes an auth check
Any friction points & auth issues
Correct answer.
If the documentation is written in multiple languages & pretty colors
Any friction points + how familiar the developer is with the docs

Question 7
What’s another great tip to take advantage of when writing good documentation?
Let your devs try it out before you publish it
Correct answer.
Translate it into 5 different languages
Only document what part of the API you worked on directly
None of the above

How to Write Good Documentation

Let’s document a fake API together

• twilio and stripe

Quiz:

Question 1
What is the prerequisite to generating any meaningful documentation?
An OpenAPI document
Correct answer.
A really cool pen
The most expensive documentation tool on the market
A background in writing

Question 2
What companies were used as examples of great documentation in this module?
Disney and Twilio
Stoplight and Spotlight
Twilio and Stripe
Correct answer.
Stripe and Bank of America

Question 3
What are the benefits of using a documentation generator?
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
All of the above
Correct answer.

---

Documentation Techniques and Tools

Quiz:

Question 1
What  is one pro of using a Spec-based method to documentation?
Either Design-first minimizes duplicated effort or it creates earlier feedback loops
Correct answer.
Everyone is doing it to so it makes it easier
All of the above
None of the above

Question 2
What are some documentation tools you can use?
Excel spreadsheets, Word doc, and Gmail
Stoplight, Swaggerhub, Readme, Redocly
Correct answer.
My notepad
None of the above

Question 3
Which of these is NOT a technique you can apply to your documentation writing?
A code annotations approach
A Spec-based approach
A bespoke approach
An API-first approach
Correct answer.

---

A few final checks before you pass this course…

Quiz:

Question 1
What are some ways you can improve your documentation in the future?
Use inclusive language
Incorporate multimedia in the docs
Create interactive docs, not just static ones
All of the above
Correct answer.

Question 2
How can you make your docs more accessible?
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
All of the above
Correct answer.

Question 3
Which is better: static or interactive docs
Static
Interactive
Correct answer.
Depends on the situation
Neither

Question 4
Are you ready to write amazing documentation?
ABSOLUTELY
Correct answer.
Almost, I need to keep studying