Project

General

Profile

Actions

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.

Status:
Resolved
Priority:
Normal
Assignee:
Category:
documentation
Target version:
-
% Done:

100%

Tags:
Backport:
Reviewed:
Affected Versions:
Pull request ID:

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".

Actions #1

Updated by Zac Dover almost 4 years ago

  • 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.

Actions #2

Updated by Zac Dover almost 4 years ago

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.)

Actions #4

Updated by Zac Dover over 3 years ago

  • 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.

Actions

Also available in: Atom PDF