plone
Remove "easily" from docs
The usage of "easily" in documentation is not cool, what is easy for you may not be easy for others.
In general this wordy and not needed. I check tells me:
Not too bad, but still we can improve that ! Plus if that is done we can add one more test to our QA setup !
And to be funny I 'just' tagged that with 'easy', hah !
'in order'?
On Wed, Mar 15, 2017 at 7:14 AM sven [email protected] wrote:
'in order' would be another good candidate
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/plone/documentation/issues/805#issuecomment-286754045, or mute the thread https://github.com/notifications/unsubscribe-auth/AAcHxuyknkR3tIsk4BE-wcJrhtyFaG4cks5rl_JRgaJpZM4Md_PA .
@fulv for example:
/manage/troubleshooting/buildout.rst:In order to show which versions were picked by buildout -
./manage/troubleshooting/buildout.rst: installation in a :term:`virtualenv`, in order not to break your OS
./manage/troubleshooting/manual-remove-utility.rst:You will need appropriate access to the zope server in order to run the site in debug mode.
./manage/troubleshooting/basic.rst:* Basic command-line knowledge is needed in order to proceed
"In order to" adds a little bit of redundancy and thus makes the sentence less likely to be misparsed. "He boarded a flight to Brazil in order to escape the law"
According to BBC World Service http://www.bbc.co.uk/worldservice/learningenglish/grammar/learnit/learnitv146.shtml , in order to "sounds a bit more formal and explicit" than to.
*In order to *is normal before a negative infinitive. We do not usually use *to *by itself here:
- *In order not to *oversleep, I set the alarm for seven o’clock.
- I walked very slowly across the room with the drinks *in order not *to spill them.
http://english.stackexchange.com/questions/3110/in-order-to-to-or-for
On Wed, Mar 15, 2017 at 10:46 AM sven [email protected] wrote:
@fulv https://github.com/fulv for example:
/manage/troubleshooting/buildout.rst:In order to show which versions were picked by buildout - ./manage/troubleshooting/buildout.rst: installation in a :term:
virtualenv, in order not to break your OS ./manage/troubleshooting/manual-remove-utility.rst:You will need appropriate access to the zope server in order to run the site in debug mode. ./manage/troubleshooting/basic.rst:* Basic command-line knowledge is needed in order to proceed— You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/plone/documentation/issues/805#issuecomment-286823736, or mute the thread https://github.com/notifications/unsubscribe-auth/AAcHxgxbJpf-FPaDBFMw8PGoLyovSrdTks5rmCP3gaJpZM4Md_PA .
Yes, but for technical writing and that is what we are doing with docs the usage of 'in order' is not recommend. There are currently huge discussions over in the whole technical writing community and the general direction is towards removal.
Writing is complex and special for technical writing with different backgrounds, language and technical skills/knowlege.
BBC is not wrong, but writing articles or stories is not the same as technical writing.
Further on as you state above it really depends on how you use it. In our docs it is more than 90% of the times 'just' wordy and adds no value.
Our docs are not written only by native or proper English speaker, that means we have to settle on a solution what works for everyone and is clear to understand and to follow.
We also want to avoid 'wrong use' which can possible lead to misunderstandings of the docs. Also tone is a important factor, wrong used could that lead to misunderstanding or misinterpretations.
There are reasons why style guides are existing. If you thing our is hard check the ones from OpenStack, Kubernetes, Twitter, Mozilla, etc :)
@svx so how do you suggest replacing the usage before a negative infinitive? e.g.:
./manage/troubleshooting/buildout.rst: installation in a
:term:virtualenv, in order not to break your OS
Also, can you point me to some discussions where the consensus is to remove "in order to"? It's just plain English, I don't see what's so bad about it.
On Wed, Mar 15, 2017 at 11:58 AM sven [email protected] wrote:
Yes, but for technical writing and that is what we are doing with docs the usage of 'in order' is not recommend. There are currently huge discussions over in the whole technical writing community and the general direction is towards removal.
Writing is complex and special for technical writing with different backgrounds, language and technical skills/knowlege.
BBC is not wrong, but writing articles or stories is not the same as technical writing.
Further on as you state above it really depends on how you use it. In our docs it is more than 90% of the times 'just' wordy and adds no value.
Our docs are not written only by native or proper English speaker, that means we have to settle on a solution what works for everyone and is clear to understand and to follow.
We also want to avoid 'wrong use' which can possible lead to misunderstandings of the docs. Also tone is a important factor, wrong used could that lead to misunderstanding or misinterpretations.
There are reasons why style guides are existing. If you thing our is hard check the ones from OpenStack, Kubernetes, Twitter, Mozilla, etc :)
— You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/plone/documentation/issues/805#issuecomment-286845297, or mute the thread https://github.com/notifications/unsubscribe-auth/AAcHxruREgr3s93tSWsbBEuBwfypsTcRks5rmDTmgaJpZM4Md_PA .
OK, maybe I try to explain better.
The idea is of course not to 'just' remove certain words, that goes hand in hand with adjusting and rewriting.
Which is a what we have to do anyway with lots of the docs since we also mixing 'active' and 'passive' voice all the time.
Documentation should be written in 'active' voice.
That goes together with adjusting the voice of our docs better to certain audiences, like writing docs for 'first time installer' should differ from docs for 'hardcore experienced plone wizards'.
Besides providing good and correct [working] content, docs should be also 'fun [but serious] and easy to read and to understand.
Writing documentation is not easy
As we said many many times before, writing and providing good docs is as equal challenging as programing.
Style guides for docs for example, are existing for the same reasons as for programing, not to make it harder but to help you, exactly for the same reason we test our docs for working links, typos and so on. Like pep8 but, then for docs.
Sadly [even is there is some light on the horizon] lots of developer still treat documentation as some unwanted evil and do not take it serious.
I am sorry there is no 'It's just plain English' this is maybe easy for you to say but, this is not true.
Not everyone is living in a English speaking country, using it on a daily basis or had the luck learning it in school.
:)
Further it is also not about 'what is so bad about it' it is about how can we make it even better.
:)
This at least what I want to do ! I want to have docs [in the long run] which I can enjoy.
This is also not something what is 'high' on my list or super urgent, but it would be nice to start somewhere and a start could be to add to our 'word choice' document that people should try to avoid that and add examples.
FTR, I totally agree with avoiding language idioms and needlessly complex phrases and sentence structure. I refereed soccer, governed by the Laws of the Game, and about 20 years ago they were overhauled massively to become more simple to support both translations and better comprehension. As a result, the reading level went from a college degree to elementary school. Some things that appear minor to native English speakers are a nightmare to translate and to preserve consistent intent in other languages. Simple things like contractions in English—"don't", "shouldn't", "we'll", "it's"—do not exist in many other languages, and should be fully spelled out. Another trend in English is to use a gender neutral term—they, them, their, its, you—and that can confuse translators who are not aware of this cultural idiom, where every object is either masculine or feminine and the neuter does not yet exist. Languages are weird.
I don't (do not) disagree with anything you guys are saying. I just find it odd to focus on "in order to", which really is not college degree level English. Sure, let's (let us) make things even better, but you have not answered my question: how do you suggest replacing the usage before a negative infinitive? e.g.: …
./manage/troubleshooting/buildout.rst: installation in a
:term:virtualenv, in order not to break your OS
I'm (I am) genuinely curious. I'm (I am) also curious to read any discussions doc writer communities have about eliminating "in order to". Does not make any sense to me.
On Thu, Mar 16, 2017 at 4:31 AM Steve Piercy [email protected] wrote:
FTR, I totally agree with avoiding language idioms and needlessly complex phrases and sentence structure. I refereed soccer, governed by the Laws of the Game, and about 20 years ago they were overhauled massively to become more simple to support both translations and better comprehension. As a result, the reading level went from a college degree to elementary school. Some things that appear minor to native English speakers are a nightmare to translate and to preserve consistent intent in other languages. Simple things like contractions in English—"don't", "shouldn't", "we'll", "it's"—do not exist in many other languages, and should be fully spelled out. Another trend in English is to use a gender neutral term—they, them, their, its, you—and that can confuse translators who are not aware of this cultural idiom, where every object is either masculine or feminine and the neuter does not yet exist. Languages are weird.
— You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/plone/documentation/issues/805#issuecomment-287030538, or mute the thread https://github.com/notifications/unsubscribe-auth/AAcHxnfWu2iaOgWvhNSm4ciSX2m3Yi7aks5rmR12gaJpZM4Md_PA .
In Plone 6, we now use Vale for style checking, following the Microsoft Writing Style Guide. See https://6.docs.plone.org/contributing/setup-build.html#vale
This will not be implemented in earlier versions of Plone docs.