Skip to content

Guide could use some copy-editing and general TLC #19335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mrhota opened this issue Nov 26, 2014 · 3 comments · Fixed by #19525
Closed

Guide could use some copy-editing and general TLC #19335

mrhota opened this issue Nov 26, 2014 · 3 comments · Fixed by #19525

Comments

@mrhota
Copy link
Contributor

mrhota commented Nov 26, 2014

There are a number of small typos in the guide, and some of the prose could be tightened up or clarified.

In general the tone of the guide comes across as trying too hard to be chatty. Keeping things casual is probably a good idea for Rust's introductory document, but we can probably remove most (all?) of the chatty prose without becoming stodgy or boring.

@huonw huonw added the A-docs label Nov 26, 2014
@apasel422
Copy link
Contributor

The guide is inconsistent with its use of certain conventions. These don't really have a correct form, but a single style should be enforced.

  • Single-quotes (') versus double-quotes (") in prose. Example:

    The first thing we'll learn about are 'variable bindings.'
    Well, Rust has this thing called "type inference."
  • Periods and commas within quotes versus without. Example:

    A struct is another form of a 'record type,'
    This operator is called 'modulo',
  • "different from" versus "different than". Example:

    This is different from named functions
    Rust's macros are significantly different than C macros
  • "filename" versus "file name"

@Gankra
Copy link
Contributor

Gankra commented Nov 26, 2014

If you find any obvious errors, or think you can write a section in a better way, please don't hesitate to submit a PR with a fix. You don't need to compile a compiler or download the source to edit the guide. You can do it all in github's ui, for the most part.

@steveklabnik
Copy link
Member

@apasel422 thanks for being specific. And for your earlier pull request. As for these...

  • They should be double quotes. Ideally, they'd even be actual curlies rather than ".
  • Periods and commas go within in almost all cases. In both of the cases you show, they should go inside.
  • "Different from" vs. "Different than" isn't something that's generally settled. Some styles choose it in different situations, others say "from" is the only correct way to say this.
  • "file name" is my preferred way, though there's no specific actual guidance.

mrhota added a commit to mrhota/rust that referenced this issue Nov 30, 2014
Made things a tad less informal, broke up Installation section with some subheaders, and adjusted some wording.

Work on rust-lang#19335.
mrhota added a commit to mrhota/rust that referenced this issue Nov 30, 2014
Further copy-editing of the Rust Guide, including some slight
adjustments in Installing Rust section, paragraph reflows up to Hello,
Cargo section and general copy clean up and clarification.

Work on rust-lang#19335
mrhota added a commit to mrhota/rust that referenced this issue Nov 30, 2014
More work on rust-lang#19335

Changes up to but not including the Strings section. Apart from
rewording some unclear, oddly-phrased, or slightly incorrect passages,
the most significant changes are the removal of short sections of code
or passages which are more appropriate for rookies than programmers who
are merely new to systems programming with Rust.
mrhota added a commit to mrhota/rust that referenced this issue Nov 30, 2014
Strings and Arrays, Vectors, and Slices sections received some editing
love.

rust-lang#19335
steveklabnik added a commit to steveklabnik/rust that referenced this issue Dec 4, 2014
mrhota added a commit to mrhota/rust that referenced this issue Dec 24, 2014
Made things a tad less informal, broke up Installation section with some
subheaders, corrected "Installing Rust", adjusted some wording,
punctuation nits, markup syntax corrections, etc.

Work on rust-lang#19335.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants