Skip to content

Migrate the API naming guidelines into the DocC catalog - #74

Merged
heckj merged 6 commits into
swiftlang:mainfrom
heckj:api-guidelines
Sep 29, 2026
Merged

heckj merged 6 commits into
swiftlang:mainfrom
heckj:api-guidelines

Conversation

@heckj

@heckj heckj commented Mar 11, 2026

Copy link
Copy Markdown
Member

Summary

This is a fairly direct migration of the API naming guidelines. The first commit is explicitly the content from the swift-org-website Jekyll based markdown, then the following commits break up that code and translate the content over to DocC format. I chose, in particular, to break this up so that each guideline became it's own "article" with a number, using a prefix of "API" for the numbering scheme, so that each one - when published - is extremely easy to reference directly with a constant URI.

This PR hasn't changed any of the content - although I'd recommend making a few basic changes that align better with our general style guidelines that have evolved since this was originally written. In particular, I'd likely remove the bold in the abstracts and remove any latin abbreviations- but I wanted to set it up for review and looking prior to any additional editorial changes for better readability.

Related Issue

Closes: #44

Testing

cd api-guidelines
swift package --disable-sandbox preview-documentation
open http://localhost:8080/documentation/apiguidelines

Build Verification

  • Ran swift package generate-documentation --analyze --warnings-as-errors successfully
  • Previewed documentation locally with swift package --disable-sandbox preview-documentation

Content Review


By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@heckj heckj self-assigned this Mar 11, 2026
@heckj
heckj requested a review from a team as a code owner March 11, 2026 21:54
@heckj heckj added content migration Content originally housed in the swift.org under /documentation/articles content review and removed content review labels Mar 11, 2026
Comment thread api-guidelines/Sources/APIGuidelines.docc/Documentation.md Outdated
@heckj
heckj force-pushed the api-guidelines branch from 054559d to 50166ff Compare July 2, 2026 20:09
@heckj

heckj commented Sep 1, 2026

Copy link
Copy Markdown
Member Author

Reset the file names to shortened slugs based on the titles and removed all the "naming/number" structured bits that I previously added.
I reworked some of the content from latin abbreviations into narrative English prose, and broke up the articles so that each abstract was a single sentence, with anything further following into an overview. (A few of these example pieces are still extremely short, but the content now feels far more consistent)
I updated some of the legacy links talking about doc comments and our "markup" format to use the DocC documentation links hosted through docs.swift.org

Visually, I'll include a couple of screenshots to make it easier to see what this looks like:

The top-level view of this collection:
Screenshot 2026-09-01 at 2 39 21 PM

An example of one of the articles with a bit of depth to it:
Screenshot 2026-09-01 at 2 39 34 PM

And one of those really "short" articles - which devolves into just a title and abstract:
Screenshot 2026-09-01 at 2 43 28 PM

@heckj
heckj requested review from a team, allevato and xwu September 8, 2026 23:47

@rjmccall rjmccall left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LSG says this looks great; thanks for doing this.

@heckj
heckj merged commit 1f9efdd into swiftlang:main Sep 29, 2026
13 checks passed
@heckj
heckj deleted the api-guidelines branch September 29, 2026 21:43
heckj added a commit that referenced this pull request Sep 30, 2026
* initial copy from swift.org website content

* initial transformation

* fairly direct translation into DocC, with minimal tweaks to align top-level formatting

* adding technology abstract for the API naming guidelines

* strip numbers and reset filenames to shorted title slugs

* rework the abstracts to english narrative prose, and fix to modern links for doc comments

(cherry picked from commit 1f9efdd)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content migration Content originally housed in the swift.org under /documentation/articles

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs migration - API Design Guidelines

4 participants