In the AI era, it is especially more imperative for APIs to be documented than ever before.
For a human, when it comes to reading source code vs reading documentation, the time difference is not too big.
However! There is a HUGE time difference between a human reading source OR documentation and an AI having proper docs to as a roadmap to quick proper code instead of unnecessarily complex workarounds, usage of a less ideal API over a better one, completely new unnecessary invented code, or hallucinations.
I beg of you, please, never release an API without documentation in the new era. Not having documentation makes AI usage a lot less efficient than it is comparing to projects with good documentation.
Documentation serves as not only a guide, but a compass that ensure AI will expand its own context in the best way possible.
I refer you to the answer provided on this topic here:
I hope you understand that when a feature is in beta (3.5 is in beta), the beta docs aren’t added to the official release docs until we reach the final release. It has always worked this way, and it makes sense. Beta features could give Meteor users the wrong impression that they’re available in the latest stable or recommended version when they aren’t.
That said, as part of new beta announcements or feature forum threads, we provide up-to-date information about the API and how to use the new feature. We also update the initial posts when new betas or changes are released, since the initial API can become obsolete.
In this case specifically, we provided the reference to the new accounts-express docs, which will be added to the official docs once Meteor 3.5 is officially released. We also have a dedicated forum post where those links are provided.
As for your comment here, I realized you didn’t check the documentation links provided in any of the announcements, or even the forum post that shows the feature with an example. You reached that conclusion later on how to use it, but all of that was already written in the docs provided.
My advice: challenge yourself, and the AI, whenever you ask about a new feature. Provide the AI with the context of the new features with all the links and information we share as part of announcements and where it’s explained. Don’t assume beta versions are available in the official docs, because they aren’t. Better to cherry-pick from our announcements and the links to docs we provide.
We get your point about documenting our APIs. As part of our release process we have a checklist item to fulfil and even an AI docs-gap skill to help us find docs coverage. For accounts-express specifically, we provided docs for it, at least to address your initial misunderstanding. Of course we can miss something, and we’re happy to get feedback and correct it. We’ll gladly address specific improvements to the existing docs that you describe.
Do you think the docs don’t reflect the new feature? We’re happy to go through each of the specific improvements you request.
So far, it seems your questions are already covered in the docs with a simple read or by providing AI context on beta features. It’s important that you read the information we provide in each beta release, where we communicate the changes in detail and include links to the relevant docs.
