I’m glad to see someone else chiming in on the topic. I’ve been working with the Fibery API regularly since 2021. My skill level at that time was beginner, today I’d consider myself an intermediate, and I’ve worked with software and developer professionals with decades of experience to integrate with Fibery. We all agree that the documentation, especially the approach to documenting the API needs work.
There’s a range between creating beginner dev friendly documentation and functional documentation for platform experts and Fibery’s API docs lean towards the latter. It’s certainly not as bad as Microsoft’s but it has the same pitfalls at a smaller scale.
- There is an astounding lack of examples and I don’t understand the determination not to add them. The documentation for the command/query API doesn’t consistently list the various input options for each command. I think esignatures is a great example of how to do this in a minimal, easy to maintain way.
- Most often, people are searching for a solution to their specific need, but Fibery documentation is written as if people read it from the beginning, master a concept, and then can refer back to those early concepts to determine the right way to accomplish specific usecases. This is not practical.
- There are workarounds of course, for example leveraging the UI as a query generator but consider why this is a preferred method. The documentation is not expansive enough. When I encounter an unexpected error, I review the documentation, notice there is a gap, and use google to find a specific reference to that exact script/api command here in the community. This is because the documentation is not specific enough to assist in troubleshooting errors. To his credit @Chr1sG is almost always involved in producing working code here in the community, but there seem to be no feedback loops that result in improved documentation. I consider the community the best reference for Fibery scripts.
I might point out here that Airtable deployed a custom api doc generator for each base in the late 10’s. That is a luxurious approach. It isn’t necessary, but a great example that flexibility is not a barrier to great docs. At the end of the day, the rules are standard and there are a fixed number of field types.
The old documentation was easier to navigate and reduced some of the friction of having to find and re-read high level concepts when working on a solution. But the new documentation in Fibery further restricts visibility into what documentation exists and where to find it.
I think better documentation would benefit not just a few power users, but overall app adoption as it would make it easier to build, ship, and market the power of Fibery. I have at several points over the years simply put off ideas and projects until I learned Fibery better or in hopes someone else will make headway and post about it to avoid some frustration.