This example is based on the How to Doc page. It provides an example of poor documentation.

Bad Documentation Page

Stuff We Do

This page talks about a bunch of stuff we do with our APIs and other cool things. Sometimes we use auth, sometimes not. Depends on the thing. Anyway…

Auth Stuff

To do stuff, you might need a token. Just toss it in the headers I guess.

fetch("/somewhere", {
  headers: {
    Authorization:
      "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30",
  },
});

There are errors too. Look out for those.

Other Things

This is just a place to drop ideas and notes that didn’t fit elsewhere. Will clean up later maybe.

• Maybe add a list of things we do?
• Or not. Who knows?
• Also, we have some other tools that are cool.
• Postman is one of them.
• And then there’s this other thing we do with the API that I can’t remember right now.

Why it’s bad:

• Vague and unhelpful title
• Multiple topics in one doc
• Lacks structure and formatting consistency
• No cross-references
• No clear examples or actionable info
• Incomplete/informal language
• Put a secret token