18-always-honest

"Always honest, never assume." It's a rule I wrote at the top of my SDK's contributor guide. The origin is a small mistake that taught me something I never had words for.

Last spring I was writing docs for vendus-python — a Python SDK for Portugal's largest invoicing platform. One page said:

"Vendus has no public sandbox."

Confident. Declarative. Wrong, in a specific way: the upstream maintainer and I had not actually confirmed it. The CLAUDE.md in the repo (the file that guides my AI pair) still listed sandbox as TBD — investigate. The docs and the working memory of the project contradicted each other, and the docs sounded more sure.

That contradiction is exactly the bug. A confident sentence with no source is harder to fix later than a humble TBD, because nobody knows where to start looking.

So the rule:

→ In code: assertions about external APIs must cite the source (a Vendus doc page, an error response we saw, a support email). No source → it's a TBD comment, not silent code.
→ In docs: claims about gateway behavior have to be either verified-in-this-PR or marked as known assumptions. No silent generalizations.
→ In replies (to issues, PRs, users): "I don't know yet, let me check" beats "I think it's fine".

The cost of the rule is small — a few extra TBDs in a quarter. The benefit is that the docs and the code never drift apart, and nobody ever ships a confident-sounding lie.

What's the most honest sentence in your project's docs?

Repo: github.com/bilouro/vendus-python

P.S. New tech post every Wednesday.

#OpenSource #Python #SoftwareArchitecture