Bad English writing

[wyuenho]

Bug report

Hi! Thanks for this awesome project. This has alleviated a lot of configuration pains. However, I have some suggestions to make:

What's wrong

Broken English in documentation and error messages all over the place, a good example is this. What do you mean "incorrect"? It's correct, the linter just suggests an alternative style with little examples and bad English to explain the rationale.

This does not help the user to improve their code, this just adds confusion, or worse, nudge the users to turn off everything they don't understand.

There are also lots of spelling errors, wrong usage of tenses, redundant words etc that make reading very unpleasant.

Even the Github issue template is bad. If should be "How should it be", not "How is that should be".

How is that should be

Get an English speaker on the team, or write strings in German, use gettext to extract them, and throw it into a service like Lokalise or Smartling to translate into English properly.

[sobolevn]

Any help in this field is appreciated! 👍

[siva432]

I would like to contribute to this :-)

[sobolevn]

@siva432 thanks a lot!

[siva432]

where or which HTML file should I edit?

[sobolevn]

@siva432 there are no HTML files to edit actually. We have two sources of docs:

• .rst files: https://github.com/wemake-services/wemake-python-styleguide/tree/master/docs and https://github.com/wemake-services/wemake-python-styleguide/tree/master/docs/pages
• .py files, like: https://github.com/wemake-services/wemake-python-styleguide/blob/master/wemake_python_styleguide/violations/best_practices.py

You can edit them! 👍

[tangowithfoxtrot]

I have made some grammar and spelling corrections to the best_practices.py file. Would you mind providing some guidance on how to contribute them? Please and thank you!

[sobolevn]

@tangowithfoxtrot do you mean #1540 ?

[siva432]

@sobolevn I have finished all changes how should resend the same PR, I tried by saving the file, git add , git push . but I'm, not receiving any PR.

[sobolevn]

@siva432 I will help you fixing the CI failure 👍

Thanks a lot for you help!

[Dreamsorcerer]

The example given is perfectly valid English. I'm not sure why you think there is a language/grammar issue there.

It's correct, the linter just suggests an alternative style with little examples and bad English to explain the rationale.

It's incorrect according to the wemake rules, which should be implied by the fact you are using wemake's opionated ruleset. I think reading the full explanation on that page is perfectly understandable for an experienced developer.

It could perhaps do with some minor improvements for less experienced developers though. For example: They may not understand some of the jargon (loop iter etc.) "...not make much sense. You can use tuples instead." Doesn't actually explain why. This is self-evident to an experienced developer, but newer developers might not understand why.

Overall, the level of English I'm seeing here is close to native, just some occassional small mistakes. So, I'm not really sure exactly why you think it's a grammar/language issue, it seems to me that maybe you're just expecting more detail? Maybe some examples of what you think it should look like would be useful?

[wyuenho]

It's everything you said plus bad English.

https://wemake-python-stylegui.de/en/latest/pages/usage/violations/consistency.html

Look at all those "Forbids to" and "Enforces to", "We do not need this since", "caused by a recent refactoring or just by acedent".... The worst thing is, these broken English is all that gets returned in the errors without the rationale or suggestions to alternatives.

[Dreamsorcerer]

Again, everything you are quoting is perfectly valid English. Could you provide an example of what you do want to see? As a native English speaker, I'm just really struggling to match your complaints with the examples provided...

[wyuenho]

First of all, fix all the spelling errors. It's accident, not acedent. Second of all, it's "we haven't needed this since" instead of "we do not need this since". "Since" implies a long time span from the past to now, so the correct usage is the present perfect tense. Apologies for leaving out the context. Third of all, don't write "forbids to use" or "enforces to have", just write out what you disallow or enforce like eslint. The "to use" and "to have" are redundant.

As someone who actually had to study English for dozens of years, I often find that native English speakers don't know their own language's grammar, because it's seldom taught in native schools.

[Dreamsorcerer]

As for missing rationale, one thing I found recommended on the website (that I didn't realise until recently), is that you can add to the flake8 config file: format = wemake This changes the output format, and includes a reminder of where all the documentation is for all of the violations. Which is handy if you're asking other developers to work on a project who are not familiar with wemake.

But, I think there should only be a one line summary in the flake8 output itself, so all the rationale, examples etc. remain in the documentation. I'd be annoyed if someone tried to put all this info into the flake8 output, so there's pages and pages of output..

[wyuenho]

That's why writing that single line error well is of paramount importance, but we shouldn't dismiss the writing in the rationale and examples sections. Even experienced dev, and I argue especially experienced devs, who don't have problems comprehending a lot of more complex Python syntax, find the rules violations mysterious, so they too have to look up the why. You cannot have a linting tool that outputs bad writing, it defeats the purpose.

[Dreamsorcerer]

"we do not need this since" is perfectly valid, since can be used as a synonym of because. That's how it's used in this context, rather than as a relation to time. In case you don't believe me, check the 8th entry here: https://www.dictionary.com/browse/since

Dropping the "to use", "to have" seems like a good suggestion. They are unneeded fluff (though it's not incorrect English).

For the record, I didn't write any of this. I'm just a user who makes occasional small contributions. I'm just a bit surprised by the description of "bad English" and then looking at something which is at least as good as a lazy native speaker. A couple of minor spelling mistakes etc.

I'd suggest making some PRs if you have any further suggestions, but if you don't have the time, I'll make a PR with those other 2 suggestions. But, until this point, I've just not seen any action points in this ticket, so that a maintainer actually knows what to do.

I've offered to review future PRs where English is a concern, so that should help stop future spelling mistakes etc. happening, but I'm not about to comb through the entire documentation myself. I'd suggest fixing things as you find issues, which is what I try to do.

[wyuenho]

since can be used as a synonym of because.

I left out the context, it's used as a reference to time.

I'm not about to touch half of the code in this project. The action point is to extract the strings and throw them onto a translation service so the pros get to handle them.

[Dreamsorcerer]

Oh, nevermind, I just reread that in context. Yes, "we do not need this since", also needs fixing.

[wyuenho]

Also, you don't get to be lazy in a linter, in writing or otherwise. A linter with unclear messages is unusable.

[Dreamsorcerer]

Translation is usually done by extracting the source strings from the code base. So, the original English strings would still need to be fixed in the code base regardless.

If the goal is to support translations to other languages, then I'd suggest updating the ticket to say exactly that. That seems like a clear feature request that could be implemented by someone.

[wyuenho]

It's already in the description.

[orsinium]

Great to see active discussion on the topic! Let's bring order here :)

1. @wyuenho please, make a PR with proposed changes. I see you have a lot of great ideas on how to make error messages better.
2. It's better to make 2 or more separate PRs for grammar fixes and for stylistic changes. The reason is that even if some stylistic changes need more discussion (like one that happens here right now), grammar fixes can be merged quite fast. Usually, grammar fixes are merged in one day: #168, #310, #971, #1374.
3. @Dreamsorcerer please, join the review when PRs are ready. I'm glad to see you so involved in the discussion.

[swapniljha001]

Is this issue already resolved? Or can I contribute something. (I had a good TOEFL score.)

[sobolevn]

@swapniljha001 you sure can! Just look through our docs for potential issues. 👍

[waterseeker]

Hi. I put in a pull request with grammar and spelling fixes for the base.py file.

[DecodersLord]

Hello, Is the issue resolved? I can contribute if needed. Can you please confirm the files that need to be edited are

• .rstfiles: https://github.com/wemake-services/wemake-python-styleguide/tree/master/docs and https://github.com/wemake-services/wemake-python-styleguide/tree/master/docs/pages

• .py files, like: https://github.com/wemake-services/wemake-python-styleguide/blob/master/wemake_python_styleguide/violations/best_practices.py

[orsinium]

This is the issue with natural languages, you can never be sure :) Just have a look at the documentation and docstrings and fix every grammar issue you find. There are definitely more of them all over the project, we're just humans and make mistakes all the time.

[sobolevn]

@DecodersLord I think that this issue cannot be resolved completely because:

• There's always something to fix (even in existing code)
• New code appears quite frequently

So, please feel free to improve any wordings you find!

Can you please confirm the files that need to be edited are

Yes, correct.

P.S. You can also take a look at https://github.com/dry-python/ I think that there are a lot of things to fix there.

[Dani-Google]

Hi I'm new here and this would be my first contribution. Can I?

[sobolevn]

Sure, please change any docs you feel like changing :) I even cannot write well in my native language 😆

[Dani-Google]

@sobolevn Thankyou 👍 You are so humble Can you assign me?

Also this link is giving error

[Dani-Google]

@sobolevn Thankyou 👍 You are so humble Can you assign me?

Also this link is giving [error](https://wemake-python-stylegui.de/en/latest/pages/usage/violations/consistency.ht

[sobolevn]

@Dani-Google done!

Our domain has changed: https://wemake-python-styleguide.readthedocs.io/en/latest/pages/usage/violations/consistency.html#consistency

[Dani-Google]

@sobolevn Ok, great :) Can you recommend me which section to check for any broken links and grammatical sections? :)

[sobolevn]

They are pretty much the same.

[Jhanvi12]

Hello , I would like to help/contribute on this project . Let me know from where to start for spelling issues.

[Aditya007Datta]

I would want to contribute to this issue

[sobolevn]

Please, feel free :)