Reviewer feedback on 'Using Git to work on the Debian Website'
Dear editors
I have written a meticulous review on the Dutch translation of
https://www.debian.org/devel/website/using_git.en.html. The review has
been sent to the mailing list of the Dutch translation team of Debian.
During the preparation of the review a number of language errors were
found in the English source text. I will list these errors below.
SOURCE TEXT
Developers can then modify the local copy and commit their changes back
to the main repository when they're ready.
CRITICISM
- The word 'then' does not follow a previous event or action.
- 'commit their changes back to the main repository' suggests that the
changes originally came from the main repository.
- The compound sentence has a coordinate structure. The first sentence
is 'Developers can then modify the local copy.'. The second sentence is
'Developers can commit their changes back to the main repository when
they're ready.'. However, 'when they're ready' in the second sentence
relates to 'modify' in the first sentence.
IMPROVED TEXT
Developers can modify their local copy and then they can commit their
changes to the main repository.
REMARK
The sentence is typical for the Debian website. The Debian website is
riddled with concoctions that seem to be the result of making paragraphs
more compact, as a sport. More examples are below.
SOURCE TEXT
Many Debian websites support SSL/TLS, so please use HTTPS links where
possible and sensible. However, some Debian/DebConf/SPI/etc websites
either don't have have HTTPS support or only use the SPI CA (and not an
SSL CA trusted by all browsers). To avoid causing error messages for
non-Debian users, please do not link to such sites using HTTPS.
CRITICISM
- It is unusual and confusing to separate enumeration items with
slashes. Slashes usually can be read as 'or', as in 'SSL/TLS' in the
first sentence.
- It is very bad style to end an enumeration with 'etc' and then make
this enumeration the first part of a noun compound.
- There is a repetition of 'have'.
- The word 'causing' can be omitted.
- It is a style error to refer with 'such sites' to an enumeration of
sites, when that enumeration already ends with 'etc'.
IMPROVED TEXT
Many Debian websites support SSL/TLS, so please use HTTPS links where
possible and sensible. However, some websites of Debian, DebConf, SPI
and others either don't have HTTPS support or only use the CA of SPI and
not a CA trusted by all browsers. To avoid error messages for non-Debian
users, please do not link to these sites using HTTPS.
SOURCE TEXT
The Git repository will reject commits containing plain HTTP links for
Debian websites that support HTTPS or containing HTTPS links for the
Debian/DebConf/SPI websites that are known to either not support HTTPS
or use certificates signed only by SPI.
CRITICISM
- It is customary and far more clear to say that links link TO somewhere
instead of saying that they link FOR somewhere.
- It is unusual and confusing to separate enumeration items with slashes.
- The word 'plain' can be omitted; the contrast between HTTP and HTTPS
is clear enough.
- The sentence is too long for comfort.
IMPROVED TEXT
The Git repository will reject commits containing HTTP links to Debian
websites that support HTTPS. Similarly, it will reject HTTPS links to
the Debian, DebConf and SPI websites that are known to either not
support HTTPS or use certificates signed only by SPI.
SOURCE TEXT
If you want to contribute to the Debian website, you need some kind of
permission to gain write access to the repository.
CRITICISM
- 'some kind of permission' is perceived as woolly language.
- The sentence contains a tautology.
IMPROVED TEXT
If you want to contribute to the Debian website, you need to gain write
access to the repository.
SOURCE TEXT
Would you be so kind and tell us more about yourself, for example, which
part of the website you plan to work on, which languages you speak, and
also if there is another Debian team member who can vouch for you.
CRITICISM
- The sentence is a question but it doesn't end with a question mark.
IMPROVED TEXT
Would you be so kind and tell us more about yourself, for example, which
part of the website you plan to work on, which languages you speak, and
also if there is another Debian team member who can vouch for you?
SOURCE TEXT
It's not necessary to get unlimited write access to the repository — you
can always submit a merge request and let other developers review and
accept your work.
CRITICISM
- 'unlimited write access' seems to be inflated language.
- The dash is incorrect here. There is not a turn in thought.
IMPROVED TEXT
It's not necessary to get write access to the repository; you can always
submit a merge request and let other developers review and accept your work.
REMARK
The phrase 'unlimited write access' was used several times earlier.
Nevertheless, the phrase seems inflated language to me. Furthermore, the
sentence
'If you need unlimited write access to the repository, e.g. if you're
about to become a frequent contributor, please request write access via
the https://salsa.debian.org/webmaster-team/webwml web interface after
logging in to Debian's Salsa platform.'
supports my opinion.
These were the errors that I found.
The Dutch translation of
https://www.debian.org/devel/website/using_git.en.html was made by Frans
Spiesschaert. You might receive further comments from him, but I am not
aware that he ever gives feedback on English source texts. Research
showed that he doesn't.
My e-mail address is on the debian-l10n-dutch mailing list, but it is
not on the debian-www mailing list.
Kind regards
Maarten
Reply to: