I noticed a couple of stylistic inconsistencies as I was reading TSPL.
TL;DR
I'm proposing to take two passes through the book:
- Fixing punctuation around code examples to conform to the style guide.
- Make conforming edits to the structure of prose around code examples to be consistent with the style guide. I do not propose to make any substantive edits to these examples or their explanations.
Punctuation
First, punctuation immediately preceding examples is often inconsistent. I checked the style guide, and that does not explain the differences.
Note: This usage isn’t entirely consistent in the existing text. We should have a discussion about this with Editorial.
I don't think that discussion has been had yet. The conventions mentioned in the guide are perfectly reasonable, of course. So, I went through The Basics and made some conforming edits. I'm going to create a PR with those so you may see.
I'm posting here because, as much as I don't mind doing this for each section of the book, I don't want to go through the entire book before getting clarification of something. The tendency throughout the book is to favor using a colon before code examples. It looks odd and is non-standard with typical English punctuation. But it was consistent enough in that direction that I thought the non-use of colons must be wrong. However, the style guide is clear about when to use colons, and its stated guideline is consistent with typical English punctuation, as well. So, I'm happy to go through and revise the remainder of the book, but I wanted to do the initial PR before proceeding. As you'll see, I used colons only where the guide indicated they should be used and removed the others.
Example Explanations
These are, for the most part, much more consistent in presentation. Indeed, they are consistent enough that the exceptions really jumped out at me the first time I encountered them. What do I mean? Let's open our hymnals to the style guide (oddly, to the section on "Tone"—another suggestion: move that into its own section):
Code listings in the guide typically follow a three part formula.... The paragraph before the code listing frames the problem that we’re trying to solve and explains what the code will do at a very high level. The paragraph (or sometimes multiple paragraphs) after the code walk through what the code listing did in more detail.
There are a few cases where this structure isn't followed, and it's noticeable. There is one example of it in The Basics, but I didn't touch that part yet.
I'm proposing to take two passes through the book:
- Fixing punctuation around code examples to conform to the style guide.
- Make conforming edits to the structure of prose around code examples to be consistent with the style guide. I do not propose to make any substantive edits to these examples or their explanations.
Edited to Add: Here's the pull request. I hope I did it right. (I did try to build it locally with docc, following the instructions provided, but that didn't work at all, even after I had docc working locally.)