Documentation #46365
closed
Developer Guide: prefer Latinate verbs to English phrasal verbs (s/show up/appear/)
Added by Zac Dover almost 4 years ago.
Updated over 3 years ago.
Description
https://docs.ceph.com/docs/master/dev/developer_guide/basic-workflow/
Here is the sentence that made me raise this Docs Bug:
In short, if your GitHub username is “mygithubaccount”, your fork of the upstream repo will show up at https://github.com/mygithubaccount/ceph.
In speech and in many contexts outside of technical writing, I like Anglo-Saxon phrasal verbs like "show up". However, when writing technical documentation for an international audience that doesn't necessarily have English as its native language, comprehension of phrasal verbs like "to show up" is less likely than the equivalent Latinate single-word (non-phrasal) verb "to appear".
- Project changed from RADOS to Ceph
- Category changed from Documentation to documentation
This page could use a general clean-up (not quite a re-write). The phrase "In short" is used here like a verbal tic, and that suggests to me that this was written in a conversational way and not carefully composed for future and repeated consumption.
If you're the guy who wrote this (probably Sage), this isn't the Day of Judgment. I don't think that the text here is bad. I just think that the verbal tics can be taken out of the text on this page so that it is easier to read.
Likewise, later in the page:
dig into
where
search
would be better. (Even though I personally enjoy the excavatory metaphor of the thoroughly Old-English-descended phrasal verb "dig into", I sacrifice my own enjoyment of this metaphor on the altar of the marginally larger audience that this document will inform if we remove it.)
- Status changed from New to Resolved
- % Done changed from 0 to 100
- Pull request ID set to 38144
This was resolved by Anthony D'Atri.
Also available in: Atom
PDF