Playbook, developer tools company
Does this work with the runtime they have already committed to
A compatibility question is asked by somebody who cannot change the answer on their side. They are on a runtime version their organisation pinned, an architecture their infrastructure team chose, or a major release they cannot upgrade this quarter. A wrong yes here becomes a support ticket. A wrong no loses the adoption silently, and often it loses it inside a document you will never see.
Why this is not the general answer
The handling pattern for compatibility questions holds across every trade. What follows is the part that does not.
- The answer is a matrix row rather than an explanation, and matrices go stale without anybody noticing because nothing breaks when they do.
- Half of these are asked before adoption, so the answer ends up quoted in an internal evaluation rather than acted on immediately.
- The real content is the removal date rather than the current state, because what the asker wants to know is how long they have.
- The reader may be on an older major release, so the correct answer is the one for their version rather than the one for the current documentation.
How it arrives
- does the client library support node 18
- is version 1 of the api still supported and until when
- can we run this on arm processors
- which python versions do you actually test against
- does it work with the latest major release of our framework
- what replaced the old webhook endpoint and when does the old one stop
What has to be indexed for this to work
| The support matrix, listing the versions you test rather than the ones you expect to work | Runtimes, operating systems, architectures and framework majors, each with the library version it applies to. The distinction between tested and probably fine is the whole value of the document, and blurring it is how a support ticket gets created. |
|---|---|
| Deprecation notices with removal dates on them | Every deprecation produces a wave of identical questions from people who did not read the changelog, and every one of those questions has a written answer already. Index the notice with its date and its removal timeline, because when does this stop working is the actual question. |
| Version labelled reference paths | Keeping each supported release on its own path is what lets an answer be attributed to a version. Drop archived releases out of the index rather than leaving them to compete with current material. |
| The migration guide for each supported jump | What changed, what breaks, and roughly what the work involves. Compatibility questions and migration questions are the same conversation ten seconds apart, and having the second answer ready is what turns a no into a plan. |
The reply
The support matrix lists Node 18 as tested for library versions in the 3 series, and the current 4 series drops it in line with that runtime reaching its own end of support. Version 1 of the interface is deprecated rather than withdrawn, and the deprecation notice carries the removal date and the list of endpoints that changed shape. If you are staying on Node 18 for now, the 3 series is still receiving fixes and the migration guide sets out what moving to 4 involves.
Every claim is tied to a version and to the document that states it, which is the only way a compatibility answer stays true after the next release. It gives the removal date rather than only the current state, because the reader is planning rather than debugging. Offering the migration guide converts a limitation into a next step without committing you to anything unpublished.
Where it stops
The trigger. The runtime, architecture or version is absent from the matrix, which makes it a roadmap question rather than a documentation one.
That combination is not in the support matrix, and whether it will be is not something I can answer from the documentation. Leave your name, your email and the exact versions you need, and somebody who works on the library will tell you where it stands.
It stops answering before it guesses, says who will pick it up, and asks for the one thing that makes a reply possible. Nothing about it reads as a dead end.
Never say this here
Out of bounds
- That something is supported because it is absent from the matrix rather than listed in it.
- A removal or end of support date that is not published in a deprecation notice.
- That a version works because a neighbouring version does.
- Any commitment about future support, including that something is likely or planned.
Questions
- Our matrix is out of date. Does that make the assistant dangerous?
- It makes it as out of date as the matrix, stated confidently. That is uncomfortable and it is also the argument for pointing it at the live page rather than an export, and for treating the questions it gets wrong as a list of rows nobody has maintained.
- Should it answer for versions we no longer support?
- It should say the version is out of support and point at the migration guide, which is a real answer. What it must not do is answer from that version's documentation as though it were current, which is why archived releases are better dropped from the index than kept in it.
- Readers ask us about compatibility with tools we have never tested. What then?
- The honest answer is that it is untested, said plainly, with the interface documentation offered so they can judge for themselves. Inferring support from architecture is exactly the kind of plausible reasoning that produces a confident wrong answer on this trade's site.
Keep reading
- Everything for a developer tools companyOn a docs site an assistant competes with search, not a phone line. Version skew, deprecations and error strings decide whether it earns its place.
- Handling compatibility questions in generalAnswerable only if you publish a list. Inferring compatibility is the failure, and the price of a wrong yes is a return and a refund.
- The only question on the site during an incident is the one it cannot answerIt reads indexed pages, so it knows what the status page said last time. Wording that points at live status instead of reporting it.
- The handover is only worth making if the version and the error text travel with itA developer handover succeeds or fails on what the form carries. The four details to gather in chat before taking a name and an email.
- Nobody is asking what it costs, they are asking what counts as oneRequests, builds, minutes or seats. What a metered price has to state before a developer can model a month and defend the number internally.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.