Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Vale linter for doc quality checks #6444

Open
Ayush9026 opened this issue Mar 28, 2024 · 4 comments
Open

Add Vale linter for doc quality checks #6444

Ayush9026 opened this issue Mar 28, 2024 · 4 comments

Comments

@Ayush9026
Copy link

Ayush9026 commented Mar 28, 2024

Description

The Vale Linter (natural language linter) implements spell check and other basic rules.

_https://github.com/errata-ai/vale

Proposed Changes:

1.Integrate a natural language linter like Vale into the Prometheus Operator documentation workflow.
2.Implement spell check and grammar rules to ensure consistent language usage across all documentation pages.
3.Define style libraries and extension points within the linter to enforce project-specific writing guidelines and conventions.
4.Configure the linter to check for common writing errors, improve readability, and suggest enhancements for technical content.
5.Provide guidelines and documentation on how contributors can use the linter during the documentation writing and review process.

Benefits:

Improved documentation quality with consistent spelling, grammar, and style.
Enhanced readability and understanding of technical content for users and contributors.
Facilitates collaboration by establishing clear writing standards and guidelines.
Supports the long-term maintainability and scalability of the Prometheus Operator documentation.

Describe alternatives you've considered.

No response

@Ayush9026 Ayush9026 added kind/feature needs-triage Issues that haven't been triaged yet labels Mar 28, 2024
@ArthurSens ArthurSens added kind/documentation and removed needs-triage Issues that haven't been triaged yet labels Mar 29, 2024
@ArthurSens
Copy link
Member

Do I understand correctly that you want to propose this linter only to markdown files?

I think it's worth trying it out and checking the results. I don't think we can fully commit until we see the suggestions the linter makes 🤔

@Ayush9026
Copy link
Author

Yes, you understand correctly. 👍 Initially, I propose integrating the Vale Linter specifically for Markdown files in the Prometheus Operator documentation. This focused approach targets spelling, grammar, and style, crucial for readability.

We'll assess the linter's suggestions to gauge effectiveness before considering wider use across different types of documentation files.

@ArthurSens
Copy link
Member

Do you want to try opening a PR with the linter?

@Ayush9026
Copy link
Author

Yes i will open PR for this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants