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.