pingcap/talent-plan

Proposed changes to README.md

The-rambunctious-S opened this issue · 0 comments

Addresses README.md

with regard to

  • writing style
  • content organization
  • grammar

In terms of writing style, these are the things that I propose changes to:

  • Voice: change the passive voice to active. So instead of saying:

As such, a series of courses focused on open source collaboration, rust programming, distributed database and systems are provided.

say:

As such, it provides a series of courses focused on open source collaboration, rust programming, distributed database and systems.

And instead of saying:

Along the way various real-world and practical Rust development subject matter are explored and discussed.

say:

We will explore and discuss various real-world and practical Rust development subject matter along the way.

Justification: See Chicago Manual of Style or Google's developer documentation style guide with regard to preferring active voice over passive.


  • Language: be accurate, specific, and concise. So instead of saying:

Each course is developed independently, so they vary in their presentation and their expectations from course-takers. Please see the individual course documentation for details.

say for example:

Each course is developed by different teams, so they may vary in their organization and learning outcomes. Please see the individual course documentation for details.

Justification: The expression "developed independently" can mean developed by a single person/team/organization or developed without cross-team collaboration. This leaves ambiguity. Also, "expectations from course-takers" comes off as a bit strange, "learning outcome" sounds more natural.

And instead of saying:

real-world and practical Rust development subject matter

say:

real-world Rust development subject matter

Justification: Real-world=practical. There is no need to paraphrase it. See 中式英语之鉴 for more information on eliminating redundancy.


In terms of content organization, these are the things that I propose changes to:

  • Include a brief introduction under level three heading before following it with a course list. So instead of saying:

Series 2: Rust Programming

Two courses are included in this series, which are:

say for example:

Series 2: Rust Programming

This series is core to TALENT-PLAN. It builds your understanding of Rust as a programming language and provides opportunities for you to practice with it. Courses include:

Justification: Change it to match they way content is organized in series 1 and give readers an idea why this series is included.

The same goes for Series 3 and 4. Might as well rearrange content to be more consistent.


In terms of grammar, these are the things that I propose changes to:

  • Use "knowledge" instead of "knowledges". So instead of saying:

It aims to create or combine some open source learning materials for people interested in open source, distributed systems, Rust, Golang, and other infrastructure knowledges.

say:

It aims to create or combine some open source learning materials for people interested in open source, distributed systems, Rust, Golang, and other infrastructure knowledge.

Justification: Knowledge is an uncountable noun and is rarely, if ever, used as countable.


  • Use hyphens in compound pre-modifiers. So instead of saying:

open source related learning mateials

say:

open-source related learning materials

Justification: See hyphen usage on Grammarly and these interesting discussions on Stackexchange: Is it correct to hyphenate with compound premodifiers? If so, where is the hyphen placed?, and Should I use “ related” or “-related”


  • Add a comma before the last item in an embedded list. Also, correct the typo. So instead of saying:

Open source collaboration includes a series of open source related learning mateials to help open source enthusiasts have a basic knowledge of what open source software is, the differences among kinds of open source software licenses, how to participate in open source projects and what a welcoming open source community looks like.

say:

Open source collaboration includes a series of open-source related learning materials to help enthusiasts gain basic knowledge of what open source software is, the differences between existing open-source software licenses, how to participate in open source projects, and what a welcoming open source community looks like.

Justification: See The Elements of Style on comma usage.


Please note that there are yet a few things that are not listed in this issue as I don't want to contaminate this place with a big chunk of grammar. If this looks OK I can submit a pull request which should look a lot more neat. Please let me know if there is anything I can help.