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.

Sign up for GitHub

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

Jump to bottom

Vale linting #61

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Vale linting #61

wants to merge 2 commits into from

Conversation

vancura
Copy link
Collaborator

@vancura vancura commented Feb 6, 2025 •
edited
Loading

This PR adds the Vale linting – so far only via Vale CLI (or extensions: VSCode, JetBrains).

The goal is to integrate Vale as a GitHub Action.

Please try Vale and see how it can be helpful for the content here. I already added some words to the dictionary (in .github/styles/config/vocabularies/Whitepaper/accept.txt), be free to add more. There are already some helpful results that we may fix quickly:

 1:1      warning  Try to keep the SMOG grade      Readability.SMOG              
                   (10.36) below 10.                                             
 1:1      warning  Try to keep the Flesch reading  Readability.FleschReadingEase 
                   ease score (64.91) above 70.                                  
 3:8      error    Use 'Whitepaper' instead of     Vale.Terms                    
                   'whitepaper'.                                                 
 6:25     warning  Prefer 'cloud' over 'the        Microsoft.Terms               
                   cloud'.                                                       
 79:6     error    Use 'Whitepaper' instead of     Vale.Terms                    
                   'whitepaper'.                                                 
 90:13    warning  Remove 'easily' if it's not     Microsoft.Adverbs             
                   important to the meaning of                                   
                   the statement.                                                
 96:1     warning  Try to avoid using              Microsoft.We                  
                   first-person plural like 'we'.                                
 96:22    error    Use 'Whitepaper' instead of     Vale.Terms                    
                   'whitepaper'.                                                 
 98:1     warning  Try to avoid using              Microsoft.We                  
                   first-person plural like 'We'.                                
 99:39    warning  Remove 'effectively' if it's    Microsoft.Adverbs             
                   not important to the meaning                                  
                   of the statement.                                             
 103:18   error    Use 'Whitepaper' instead of     Vale.Terms                    
                   'whitepaper'.                                                 
 105:64   warning  'is provided' may be passive    write-good.Passive            
                   voice. Use active voice if you                                
                   can.                                                          
 110:42   warning  'implement' is too wordy.       write-good.TooWordy           
 111:19   error    Use 'Whitepaper' instead of     Vale.Terms                    
                   'whitepaper'.                                                 
 115:44   warning  Prefer 'cloud' over 'the        Microsoft.Terms               
                   cloud'.                                                       
 120:36   warning  'be restarted' may be passive   write-good.Passive            
                   voice. Use active voice if you                                
                   can.                                                          
 137:79   warning  Remove 'easily' if it's not     Microsoft.Adverbs             
                   important to the meaning of                                   
                   the statement.                                                
 140:12   warning  Remove 'easily' if it's not     Microsoft.Adverbs             
                   important to the meaning of                                   
                   the statement.                                                
 148:12   warning  'be published' may be passive   write-good.Passive            
                   voice. Use active voice if you                                
                   can.                                                          
 151:33   warning  'in order to' is too wordy.     write-good.TooWordy           
 167:54   error    Use 'they're' instead of 'they  Microsoft.Contractions        
                   are'.                                                         
 173:12   warning  'is passed' may be passive      write-good.Passive            
                   voice. Use active voice if you                                
                   can.                                                          
 256:61   warning  'be used' may be passive        write-good.Passive            
                   voice. Use active voice if you                                
                   can.                                                          
 280:115  error    Use 'for example' instead of    Microsoft.Foreign             
                   'e.g.'.                                                       
 435:49   warning  'various' is a weasel word!     write-good.Weasel             
 448:24   warning  Try to avoid using              Microsoft.We                  
                   first-person plural like                                      
                   'our'.                                                        
 491:71   warning  'implement' is too wordy.       write-good.TooWordy           
 1727:31  warning  'be hosted' may be passive      write-good.Passive            
                   voice. Use active voice if you                                
                   can.                                                          
 1730:30  error    Use 'Whitepaper' instead of     Vale.Terms                    
                   'whitepaper'.                                                 
 1739:41  warning  'usually' is a weasel word!     write-good.Weasel             
 1760:15  warning  Prefer 'cloud' over 'the        Microsoft.Terms               
                   cloud'.                                                       
 1760:72  warning  Remove 'easily' if it's not     Microsoft.Adverbs             
                   important to the meaning of                                   
                   the statement.                                                
 1765:15  warning  'is developed' may be passive   write-good.Passive            
                   voice. Use active voice if you                                
                   can.                                                          
 1777:30  warning  'usually' is a weasel word!     write-good.Weasel             
 1806:18  error    Use 'Whitepaper' instead of     Vale.Terms                    
                   'whitepaper'.                                                 
 1808:29  warning  'however' is too wordy.         write-good.TooWordy           
 1810:3   warning  'Finalize' is too wordy.        write-good.TooWordy           
 1811:3   warning  'Clearly' is a weasel word!     write-good.Weasel             
 1811:20  error    Use 'what's' instead of 'what   Microsoft.Contractions        
                   is'.                                                          
 1811:57  error    Use 'what's' instead of 'what   Microsoft.Contractions        
                   is'.                                                          
 1817:26  error    Punctuation should be inside    Microsoft.Quotes              
                   the quotes.                                                   
 1817:27  error    Don't use 'backend'. See the    Microsoft.Avoid               
                   A-Z word list for details.                                    

✖ 13 errors, 29 warnings and 0 suggestions in 1 file.

(These are results of README.md; there are a couple of files in /pages too, but they're not shown here)

The question is if we need Readability.FleschReadingEase and Readability.SMOG. Maybe that's too restricting, but I will leave the decision to you :)

Thanks, @TC-MO, for starting this and helping with the integration and config file.

/c @davidjohnbarton, @OlikEten, @jancurn @netmilk

Fixes: #60

@vancura vancura added documentation Improvements or additions to documentation enhancement New feature or request labels Feb 6, 2025
@vancura vancura marked this pull request as draft February 6, 2025 12:07
@vancura vancura self-assigned this Feb 6, 2025
@TC-MO
Copy link
Contributor

TC-MO commented Feb 6, 2025

For my 2 cents I'll say that I see the value in seeing the readability scores, but wouldn't treat them as be all & end all goal. As long as they are setup as warnings they are something to strive for but not be completely beholden to.

@vancura
Copy link
Collaborator Author

vancura commented Feb 6, 2025

Thanks for the approval, @jancurn, but this is a draft for now :)

If everyone is happy with the proposed workflow, I will create a GitHub action, and we'll see how it goes. I suppose it will be really noisy, and we'll need to work on the Whitepaper copy further to make Vale happy.

@jancurn
Copy link
Member

jancurn commented Feb 6, 2025

Thanks, that was a bianco cheque pre-approval :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jancurn jancurn jancurn approved these changes

Assignees

@vancura vancura

Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Vale integration
3 participants
@vancura @TC-MO @jancurn