I've learned a lot about building threat intelligence APIs the last few years. Simpler is better than complex, examples are better than solid developer documentation and no matter how good (or bad) something is, you will always get questions. Questions from those who don't read and questions from those who spend hours pulling their hair out before emailing you when you clearly have a giant gaping hole in the doc.
Writing documentation is hard, no matter how detailed you are, or how much time you spend on it you're always going to miss something. The only solution is constant interaction with users and releasing new updates. What you learn over time is there's two different types of documentation, the advanced technical doc and the examples. What most authors start out with is the technical doc in hopes of "being complete".
This methodology fails when "normal" users try to view the doc through the problem they're trying to solve. Instead of building an API and set of technical docs by example, we build functions, methods and "sexy" first, then try to bend our technical specifications to the examples. We should be building the examples first, identifying the problems we're solving (eg: search), then building APIs and technology to solve those problems.
As the technology becomes more advanced and complex, we should be documenting those things behind the scenes. We should be hiding that documentation from the 90% of beginners who have no need for it. Complex technical documentation is the thing that creates the most friction in most projects. If the "hello world" search example isn't at the top of the readme, you're doing it wrong. Don't explain what your project IS, describe what it SOLVES and give examples.
If your goal is "the fastest way to consume threat intelligence" then the readme should show me how to solve these problems in 5 lines of python. I shouldn't have to think- I should only need to copy paste. Get me to the answer in the 30s or less, otherwise I'm moving onto the next shiny project. Once I'm hooked- then I can wander through the more technical doc if/when I run into problems. Doc is about making me comfortable in your ecosystem, too much too soon and I get scared. Leave me some breadcrumbs, let me get used to the water before I dive dive in.
Interactive examples are also an added bonus in interacting with a new technology. Things like OpenAPI where the documentation is not only auto-generated, it enables you to actually query the system LIVE. This has the added bonus of documenting how the system works, but helps me write my own integrations with a nice set of guard rails. It's harder to make mistakes when you have a live, transparent sandbox to leverage. It's like having the developer right there with you, guiding you through the process.
