Copyedits of TSPL

Swift Documentation
1

I noticed a couple of stylistic inconsistencies as I was reading TSPL.

TL;DR

I'm proposing to take two passes through the book:

  1. Fixing punctuation around code examples to conform to the style guide.
  2. 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. :joy: 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:

  1. Fixing punctuation around code examples to conform to the style guide.
  2. 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. :grimacing: (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.)

1 Like
2

Thanks for starting the work here to clean up TSPL for a more consistent style here!

You're correct — I haven't had a discussion with Editorial about this. According to git blame that note has been in the TSPL style guide since 2019, so it's been on our "would be nice to fix" list for quite a while.

Since this week is WWDC, I'm not expecting to have a lot of time to talk about it. Likewise, I'm not expecting the editors to have a lot of time to talk about it until next week.

In the mean time, do you mind converting the PR to a draft? That reflects the fact that it's not ready for people to review the changes yet.

1 Like
3

No problem! Let me say, by way of preface and in order to establish a working framework for interpreting everything I say about this, I know in a list of priorities from 1..100 (with 1 being most urgent) this is 100. But it's a way (albeit a teensy, tiny way) that I can contribute, so I'm happy to do it.

Understandable! (See above.)

As for timing, I assumed there would be no movement on this until at least next week if not later in the summer, given both WWDC and where this falls in terms of priorities. My plan was to gently nudge this issue again in a couple of weeks if I hadn't heard back. The only constraint for me is that I'm a public high school teacher, and our new year begins in August. Ideally I'd be able to get most of this done before then.

I assume this means withdraw the PR request. I don't know what it means to convert it into a draft, though. Just leave it in the fork of the repo I made and mark it DRAFT or something like that?

Thanks for getting back to me! As I said in the PR thread, I view my role here as secretarial in nature, not substantive, so I'll be looking to y'all for my directions.

-DV.

4

I figured out you (obviously) meant make it a draft pull request, went to do that, and saw you had already done it. My bad! I am, in fact, an idiot. :rofl::joy:

5

Thanks again for your work here so far — this kind of "clean up" throughout the book is very valuable!

To give a brief update, the editor I want to discuss this style rule with was on vacation for a week or two. I also compared the TSPL style guide against the style guide we use for writing Apple's developer documentation. I think both style guides agree, and match the changes you've made so far — but they're also both very brief. I think the style guide needs a slightly longer discussion, to help make the right way to do this clearer.

I'm hoping to draft an update to the style guide and discuss with editorial in the next week or so.

6

Thanks for getting back to me. It sounds like the substantive (as it were) edits I made, then, are along the lines y'all wanted for consistency's sake (as opposed to the suggestion made on the draft PR, to rethink the style guide's guidelines). It's true that the style guide itself could use some work, but I (think?) I understood the driving principle, so:

I'll go ahead and work through the remaining sections of the book and make conforming edits, just to get the bulk of that out of the way. If revising the style guide itself results in needing to tinker with (some of) the changes again, I can revisit it, but it sounds like this is generally the direction it's heading in.

7

Do you mind waiting a couple days before you do? I think these edits match the desired Apple style, but I'm not 100% sure. I wouldn't want to waste your time if I'm misreading a style guide.

1 Like
8

Nope, I'll wait to hear from you. Thanks for being so responsive on all this!

9

One of the editors will look at this PR on Monday. Thanks again for waiting while the editors balance work on several projects.

1 Like