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

docs(react): revise for clarity, grammar, and formality #197

Merged
merged 1 commit into from Nov 6, 2018

Conversation

Projects
None yet
4 participants
@kkwoker
Contributor

kkwoker commented Nov 6, 2018

Overview

I'm taking a course on technical writing and wanted to help improve some of the documents here on Reference Architecture. My semester assignment is to complete 10 open sourced edits on the web and this felt like a great place to start.

In class, we learned about common issues in technical writing such as concision, cohesion, tone and structure. Fixing these issues improve clarity, reader’s understandability and maintains the author's trustworthiness.

I hope some of these revisions are helpful to you and am open to further suggestions.

Details

The reason why the Why section has changed to bullet points is that the entire paragraph reduces to a list of items required when choosing React. The point form bulleted structure is easier to understand for listed attributes in technical writing.

In the What and How section, conversational colloquialisms are removed in favour for a more formal style. Pronouns such as "you" or "our" are removed to be more formal.

In the What section, there's some embedding of extra information that can be removed to improve clarity. For example, some of the parenthetical information given such as "(called "state")" or "(in a format known as "JSX")" can be taken out. The audience for this document is able to read more information through the links provided rather than trying to understand it here.

Side note on quotation marks around single words:
There are some cases where quotation marks are used around a single word. These are called "scare quotes" and are used for emphasis only when quoting words someone else used. It usually implies that the author does not agree with the use of the terms. Reference: https://www.grammarly.com/blog/quotation-marks-around-a-single-word/


Meta

Please read and confirm each of the following:

  • this topic was discussed in the Technology Forum (ignore if the pull request represents small changes)
  • provided a descriptive topic and overview of contribution
  • documentation format follows the topic template
  • fork is up to date (Hint: "Syncing a Fork")
  • "work in progress" commits are squashed (Hint: "Squashing Commits")
  • commits follow the Conventional ChangeLog format
  • no sensitive content included, such as:
    • content considered competitive intelligence
    • security & privacy policy violating content
    • keys, tokens or credentials
docs(react): revise for clarity, grammar, and formality
The reason why the Why section has changed to bullet points is that
the entire paragraph reduces to a list of items required when choosing React.
The point form bulleted structure is easier to understand for listed attributes in
technical writing.

In the What and How section, conversational colloquialisms are removed
in favour for a more formal style.

Links to more information on how React works is given rather than trying
to explain it all in this document.

There are some cases where quotation marks are used around a single word.
These are called "scare quotes" and are used for emphasis only when
quoting words someone else used. It usually implies that the author does not agree
with the use of the terms. Reference: https://www.grammarly.com/blog/quotation-marks-around-a-single-word/

@kkwoker kkwoker requested a review from ruxandrafed Nov 6, 2018

@kkwoker kkwoker requested a review from telus/architecture-support as a code owner Nov 6, 2018

@ahmadnassri ahmadnassri merged commit ab04fb0 into telus:master Nov 6, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment