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