In any case, this might actually be a good use for an LLM to post-process it into whatever style you want. I bet there's even a browser extension that could do it on-demand and in-place.
- I support the creation of schemas for any primitive data type.
- Among complex values I support objects, records, arrays, tuples as well as various other classes.
- For objects I provide various methods like pick, omit, partial and required.
- Beyond primitive and complex values, I also provide schema functions for more special cases.
Same for "Mental model", "Pipeline", "Parse data", "Infer types", "Methods" and "Issues" - I'll assume the other sections also follow this style. That's all not showing up for you?
While the LLM suggestion is nice, it's not something I'm comfortable with unless hallucinations are incredibly rare. Why would I use a library whose documentation I have to pass through an unreliable preprocessor to follow a normal style?
I honestly don't want my validation library to "tell a story" at the expense of documentation clarity. It's absolutely fine that this project uses it, I don't want to impose my view on them - I guess it's just not the validation library for me.
Not an issue for me, to be honest. Why does it bother you at all?
1. The biggest part is that I've simply never seen documentation written in this style, any mentions of "I" or "we" are usually explaining the choices made by the author(s). When skimming documentation I pay more attention to those parts. Here those parts don't have a comparable meaning.
2. The smaller part is that the writing style reminds me of the way brands use mascots with first-person writing to advertise to children. There's not really any other association I have with this way of writing, and it makes me feel like the author either isn't taking the project seriously, or me.
I'm not trying to argue that the documentation should be understood this way, or that it should be changed - but I've stumbled over this multiple times, and can't imagine that it's just me.
I think a more important issue is that Valibot hasn't reached 1.0 yet. But it looks like it's very close.
In the software field you get a large portion of people that don't buy into the concept of professionalism. For various reasons - chiefly the hacker culture and the easy of contributing to the "field" means the gauntlet one runs to become a "professional" isn't inherently a given.
As a whole this is a good thing but it does mean if you operate as a "professional" maybe sometimes you have to realize that something doesn't exactly gel with your ethos (case in point). It doesn't mean it is bad; just maybe not for you and yours.
There's still more at play, since I really keep visually stumbling over those sentences, but that seems to be more related to me. And you're absolutely right that this doesn't make the project objectively worse - I wish them best of luck and hope their approach to documentation helps others!