6
4 Comments

2 ways to ensure your documentation doesn't fail

Auto-generate your docs based on the OpenAPI spec or use Postman

One of the most annoying things is to follow some form of documentation and none of your API calls work. As a product owner, this is not what you want your early adopters to go through.

From what I have seen most times API docs fail because the code sample or instructions are wrong or out of date.

One way to keep an up to date and accurate docs as possible is to publish the working sample you use during development.
A tool such as Postman allows you to polish up your dev API calls and publish them as API docs.

Another way is to document your APIs using the OpenAPI standard. This provides you with ready-to-use code in addition to interactive docs. I personally despise the look of the interactive docs, you might want to try Redocly instead.

Have a group for when the docs fail

This is not likely to scale over time, but it's a good thing to have this early on.
Be it Slack, Telegram, or a good old Forum, having a place where a user can seek help or ask questions could help avoid churn. A user is more likely to reach out if they have a few successes trying out your product but then hit a block.

The other good thing with having a group is that you are able to collect some useful feedback as well, such as ideas on what else needs to be documented or added to your blog.

I am currently working on contentfordevs and will be more than happy to work with anyone looking to improve their documentation or grow their blog with technical content.

on March 9, 2022
  1. 2

    Solid advice, thank you! 🙏

    1. 1

      Glad you found it useful 🙂

  2. 1

    @eddymens our company provides a bunch of APIs to customers and documentation is a major pain point. So crucial to success, but difficult to keep up with (especially at first).

    I'm curious though - why do you "despise the look of the interactive docs"? I think one nice thing about a lot of those interactive doc tools is they also provide API server mocking, which helps other teams start developing while you finish the API.

    1. 1

      @alex_docugraph oh yes the Swagger toolkit is very useful. I meant the look and feel of the interactive docs itself, it hasn't changed much and looks outdated by today's standard.
      If you need help keeping your docs up to date, its something I can help with, just let me know :)

Trending on Indie Hackers
AI runs 70% of my distribution. The exact stack. User Avatar 73 comments Show IH: I'm building a lead gen + CRM tool for web designers targeting local businesses without websites — starting with Spain User Avatar 69 comments I'm a solo founder. It took me 9 months and at least 3 stack rewrites to ship my SaaS. User Avatar 60 comments I built a URL indexing SaaS in 40 days — here's the honest story User Avatar 56 comments We witnessed a sharp spike in our traffic. So much happiness after a long time. User Avatar 15 comments We could see our AI bill, but not explain it — so I built AiKey User Avatar 11 comments