Consider using Vale as part of Docs workflow

theprogram commented

2026-02-21 11:43:31 +00:00

Member

Hank has proposed using Vale part of our Docs contibutor pipeline.

We briefly talked about it in the Matrix chat, and understand there is a tension between 'ease of contribution' and 'professional documentation'.

It would be great to hear what others think about using Vale (a professional grammar and style checker) as part of the Docs pipeline.

Hank has proposed using Vale part of our Docs contibutor pipeline. We briefly talked about it in the Matrix chat, and understand there is a tension between 'ease of contribution' and 'professional documentation'. It would be great to hear what others think about using Vale (a professional grammar and style checker) as part of the Docs pipeline.

pg-tips commented

2026-02-21 11:56:49 +00:00

Member

Could we see some examples of the kind of corrections that Vale would make?

Of course it's good to catch things that are clearly typos, but a downside of grammar checkers is that they can impose "rules" which push writers towards an overly "dry" and stereotyped style of English which becomes less engaging and therefore less readable. IMO, on a FOSS project we wouldn't want to focus so much on using 'professional' language that we overshoot and end up writing in corporate-speak.

I find some of these perspectives useful on the downsides of over-rigid adherence to a style guide: https://archive.nytimes.com/roomfordebate.blogs.nytimes.com/2009/04/24/happy-birthday-strunk-and-white/

Could we see some examples of the kind of corrections that Vale would make? Of course it's good to catch things that are clearly typos, but a downside of grammar checkers is that they can impose "rules" which push writers towards an overly "dry" and stereotyped style of English which becomes less engaging and therefore less readable. IMO, on a FOSS project we wouldn't want to focus so much on using 'professional' language that we overshoot and end up writing in corporate-speak. I find some of these perspectives useful on the downsides of over-rigid adherence to a style guide: https://archive.nytimes.com/roomfordebate.blogs.nytimes.com/2009/04/24/happy-birthday-strunk-and-white/

hricky commented

2026-02-21 12:11:32 +00:00

Owner

@theprogram wrote in #9 (comment):

We briefly talked about it in the Matrix chat, and understand there is a tension between 'ease of contribution' and 'professional documentation'.

Personally, I'm all for implementing Vale linting in our CI pipeline and I don't see how it would negatively impact "ease of contribution".

@pg-tips wrote in #9 (comment):

Of course it's good to catch things that are clearly typos, but a downside of grammar checkers is that they can impose "rules" which push writers towards an overly "dry" and stereotypes style of English which becomes less engaging and therefore less readable.

Our documentation is for the most part highly technical instructions on how to use/administer a Linux distribution, not a work of literary fiction.

@theprogram wrote in https://forge.fedoraproject.org/docs/tickets/issues/9#issue-94239: > We briefly talked about it in the Matrix chat, and understand there is a tension between 'ease of contribution' and 'professional documentation'. Personally, I'm all for implementing Vale linting in our CI pipeline and I don't see how it would negatively impact "ease of contribution". @pg-tips wrote in https://forge.fedoraproject.org/docs/tickets/issues/9#issuecomment-540965: > Of course it's good to catch things that are clearly typos, but a downside of grammar checkers is that they can impose "rules" which push writers towards an overly "dry" and stereotypes style of English which becomes less engaging and therefore less readable. Our documentation is for the most part highly technical instructions on how to use/administer a Linux distribution, not a work of literary fiction.

pg-tips commented

2026-02-21 12:23:00 +00:00

Member

@hricky wrote in #9 (comment):

Our documentation is for the most part highly technical instructions on how to use/administer a Linux distribution, not a work of literary fiction.

The "Beginner's Guide" that we've been discussing is one place where I think tone of voice would be important. We'd want that to be written in a way that feels engaging and approachable.

@hricky wrote in https://forge.fedoraproject.org/docs/tickets/issues/9#issuecomment-540966: > Our documentation is for the most part highly technical instructions on how to use/administer a Linux distribution, not a work of literary fiction. The "Beginner's Guide" that we've been discussing is one place where I think tone of voice would be important. We'd want that to be written in a way that feels engaging and approachable.

hricky commented

2026-02-21 13:46:54 +00:00

Owner

@pg-tips wrote in #9 (comment):

The "Beginner's Guide" that we've been discussing is one place where I think tone of voice would be important. We'd want that to be written in a way that feels engaging and approachable.

I was under the impression that this ticket was about the Fedora Docs in general, not a specific section. I don't know what this "Beginner's Guide" is intended for, nor in what tone or manner it is intended to be written. On this topic, if anyone is interested, I could provide links to courses that I personally find very useful and from which I have learned a lot.

@pg-tips wrote in https://forge.fedoraproject.org/docs/tickets/issues/9#issuecomment-540967: > The "Beginner's Guide" that we've been discussing is one place where I think tone of voice would be important. We'd want that to be written in a way that feels engaging and approachable. I was under the impression that this ticket was about the Fedora Docs in general, not a specific section. I don't know what this "Beginner's Guide" is intended for, nor in what tone or manner it is intended to be written. On this topic, if anyone is interested, I could provide links to courses that I personally find very useful and from which I have learned a lot.

pg-tips commented

2026-02-21 14:20:00 +00:00

Member

@hricky wrote in #9 (comment):

I was under the impression that this ticket was about the Fedora Docs in general, not a specific section.

Absolutely, which is why I'm expressing potential concerns with the imposition of a single, linter-enforced style across the whole landscape of Fedora Docs.

The proposed Beginner's Guide was fresh in my mind and felt to me like a particularly salient example where an overly dry style could detract from the aims of the documentation.

But it all depends exactly what rules we'd be trying to enforce, of course. And perhaps we could consider different rulesets for different areas of documentation.

@hricky wrote in https://forge.fedoraproject.org/docs/tickets/issues/9#issuecomment-540968: > I was under the impression that this ticket was about the Fedora Docs in general, not a specific section. Absolutely, which is why I'm expressing potential concerns with the imposition of a single, linter-enforced style across the whole landscape of Fedora Docs. The proposed [Beginner's Guide](https://forge.fedoraproject.org/docs/tickets/issues/8) was fresh in my mind and felt to me like a particularly salient example where an overly dry style could detract from the aims of the documentation. But it all depends exactly what rules we'd be trying to enforce, of course. And perhaps we could consider different rulesets for different areas of documentation.

hricky commented

2026-02-21 20:43:32 +00:00

Owner

I'm not entirely sure whether dividing the Fedora docs into stylistic (and therefore somewhat less technical content-related) distinct sections would be beneficial in any way.

pg-tips commented

2026-02-21 21:15:26 +00:00

Member

@hricky wrote in #9 (comment):

I'm not entirely sure whether dividing the Fedora docs into stylistic (and therefore somewhat less technical content-related) distinct sections would be beneficial in any way.

I'm not entirely sure either! It's really going to depend on the details of the rules that are proposed.

A draft of the Beginner's Guide is available now, and it does a good job of finding the right tone of voice for its intended audience. So a good test of the rules would be whether that guide can comply with them while retaining its style.

@hricky wrote in https://forge.fedoraproject.org/docs/tickets/issues/9#issuecomment-540978: > I'm not entirely sure whether dividing the Fedora docs into stylistic (and therefore somewhat less technical content-related) distinct sections would be beneficial in any way. I'm not entirely sure either! It's really going to depend on the details of the rules that are proposed. A draft of the Beginner's Guide is available now, and it does a good job of finding the right tone of voice for its intended audience. So a good test of the rules would be whether that guide can comply with them while retaining its style.

hricky commented

2026-02-21 21:32:21 +00:00

Owner

IMHO, the way this guide is currently written is more suitable for Fedora Magazine than Fedora Docs, but this discussion is probably more appropriate for the guide's ticket.

jflory7 commented

2026-02-24 15:34:20 +00:00

Owner

Ran out of time to discuss in 2026-02-24 Docs Team meeting.

We did not discuss this ticket in today's meeting, even though it did make the agenda. We encouraged Docs Team members to weigh in asynchronously on this issue.

_Ran out of time to discuss in [2026-02-24 Docs Team meeting](https://discussion.fedoraproject.org/t/docs-team-meeting-2026-02-24-simplifying-contributions-and-supporting-new-fedora-users/181834)_. --- We did not discuss this ticket in today's meeting, even though it did make the agenda. We encouraged Docs Team members to weigh in asynchronously on this issue.