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(versioning): improve clarity, grammar and formality #198

Merged
merged 1 commit into from Nov 7, 2018

Conversation

Projects
None yet
4 participants
@kkwoker
Contributor

kkwoker commented Nov 7, 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

It is worth noting that under the section What, the last sentence "In some cases, this is not necessary, and simple incremental major version numbers is also acceptable." requires further elaboration. When is it okay to not use semantic versioning? How does the reader choose whether to use semantic versioning or not?

In the section under API versioning, I had a hard time deciphering whether versioning should be avoided in APIs or not. The phrase “Typically we would avoid using versions,” suggests we should avoid versioning, however “For our API platform services, we most likely need to version them” suggests we should use versioning. I left the phrasing in a format of a conditional which is only if the API requires versioning.

I also had a difficult time clarifying the recommendations for API versioning but I hope the revision makes it understandable enough.


Meta

  • 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

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

@ahmadnassri ahmadnassri merged commit 29d87bb into telus:master Nov 7, 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