Skip to content

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

Open
heckj wants to merge 6 commits into
swiftlang:mainfrom
heckj:api-guidelines
Open

Migrate the API naming guidelines into the DocC catalog#74
heckj wants to merge 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
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

3 participants