Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
docs(react): revise for clarity, grammar, and formality #197
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.
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: