5 ms·

I recently stumbled onto this when looking for alternatives, and though it might sound a bit extreme: the style of documentation means I'll never consider it fo

by Timon3 2y ago

I recently stumbled onto this when looking for alternatives, and though it might sound a bit extreme: the style of documentation means I'll never consider it for any project. It's strange and honestly somehow unnerving to read documentation written from a first-person perspective. Is there some good reason for this that I'm missing? Or am I just crazy and this isn't an issue for anyone else?

Bjartr 2y ago
I only see second-person "you" and not first-person "I" in the linked documentation. Am I missing what you intended to point out? 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.
- Timon3 2y ago
  Really? For example under "Main concepts" on the "Schemas" site[0], I see stuff like this: - 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? [0]: https://valibot.dev/guides/schemas/ https://valibot.dev/guides/schemas/
  - prophesi 2y ago
    If they're part of Hacktoberfest, editing those pages to drop the first person perspective sounds like a pretty useful first contribution.
    - Timon3 2y ago
      It seems I'm not the first person to make this observation: https://github.com/fabian-hiller/valibot/issues/687 https://github.com/fabian-hiller/valibot/issues/687 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.
kaoD 2y ago
> Or am I just crazy and this isn't an issue for anyone else? Not an issue for me, to be honest. Why does it bother you at all?
- Timon3 2y ago
  I'm not exactly sure myself, but every time I open one of the pages, I mentally stumble over the formulations. I think there are two components: 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.
skybrian 2y ago
It's a little too cute, but I don't see it as a deciding factor on which library to use. I think a more important issue is that Valibot hasn't reached 1.0 yet. But it looks like it's very close.
wruza 2y ago
Yes, that's just cringe.
aswerty 2y ago
I don't think you are crazy at all. The concept of professionalism is about doing things a certain way to indicate to others that you are, of course, a professional. Writing technical documents in the 3rd person is a basic part of what I would consider professionalism in the broader engineering field. 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.
- Timon3 2y ago
  Thank you for sharing your perspective, I hadn't really thought about that angle. If a colleague asked me to explain my choice, I feel there'd be some appearance of being convinced by style over substance. 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!

by Timon3 2y ago

Bjartr 2y ago

I only see second-person "you" and not first-person "I" in the linked documentation. Am I missing what you intended to point out? 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.

Timon3 2y ago
Really? For example under "Main concepts" on the "Schemas" site[0], I see stuff like this: - 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? [0]: https://valibot.dev/guides/schemas/ https://valibot.dev/guides/schemas/
- prophesi 2y ago
  If they're part of Hacktoberfest, editing those pages to drop the first person perspective sounds like a pretty useful first contribution.
  - Timon3 2y ago
    It seems I'm not the first person to make this observation: https://github.com/fabian-hiller/valibot/issues/687 https://github.com/fabian-hiller/valibot/issues/687 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.

kaoD 2y ago

> Or am I just crazy and this isn't an issue for anyone else? Not an issue for me, to be honest. Why does it bother you at all?

Timon3 2y ago
I'm not exactly sure myself, but every time I open one of the pages, I mentally stumble over the formulations. I think there are two components: 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.

skybrian 2y ago

It's a little too cute, but I don't see it as a deciding factor on which library to use. I think a more important issue is that Valibot hasn't reached 1.0 yet. But it looks like it's very close.

wruza 2y ago

Yes, that's just cringe.

aswerty 2y ago

I don't think you are crazy at all. The concept of professionalism is about doing things a certain way to indicate to others that you are, of course, a professional. Writing technical documents in the 3rd person is a basic part of what I would consider professionalism in the broader engineering field. 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.

Timon3 2y ago
Thank you for sharing your perspective, I hadn't really thought about that angle. If a colleague asked me to explain my choice, I feel there'd be some appearance of being convinced by style over substance. 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!