Hi,
What’s the difference between
and
Thank you
The Swift standard library defines a base layer of functionality for writing Swift programs. Documentation for the standard library is presently hosted on the Apple Developer website.
The Swift standard library, along with its tests and inline documentation, are a part of the main Swift repository.
The Swift Programming Language is the authoritative reference for Swift, offering a guided tour, a comprehensive guide, and a formal reference of the language.
- The Swift Programming Language Book | Language reference | Swift.org
To illustrate the difference you can look at these two which discuss strings
2 Likes
The Apple docs just provide a quick summary of what Swift is and then link to Swift.org, don't really understand where the confusion comes from. As @MinerMinerMain mentioned, the standard library documentation is hosted on the Apple developer website, but you won't find, for example, an overview of Swift's concurrency model here, albeit, in my opinion, the language documentation on Swift.org is currently severely lacking. As an example, to get an understanding about the execution semantics of asynchronous functions, you actually have to find this very specific API documentation here or read the corresponding Swift Evolution proposal.
1 Like
The documentation hosted at Featured | Apple Developer Documentation is the hosted location for Apple's developer documentation, which includes documentation for the Swift open source project.
The documentation hosted on Swift.org (most of it hosted through as Jekyll articles or as DocC archives published at swift.org or docs.swift.org) has grown organically. Multiple of the workgroups have been pushing to have improved documentation, and earlier in 2025 I started an effort to formally pull it together and provide some organization and common content. There is work ongoing currently to bring the Swift Standard Library to be hosted with the other documentation on swift.org, as well as re-organize the content slightly for consistency, building on the structure that we have today for language reference guide at The Swift Programming Language.
If you're curious about the proposal, it's available at swift-org-website/_info-architecture/0003-swift-docs-proposal.md at main · swiftlang/swift-org-website · GitHub, and it being carefully coordinated with the schedules and availability of the Website Workgroup, the Documentation Tooling workgroup, and the team that manages the public infrastructure for Swift.org.
We still have some pieces to sort out - in particular the URI layout for the publishing of multiple DocC archives, and how to visually align and interconnect any hosted documentation with the current Swift.org redesign, which has been progressing since WWDC of 2025. To a large extent, I stepped into that work after it started and have been working to align this update to fit well within that project's scheduled and expected efforts.
I expect we'll resume working on after the holiday break, and as establish the structure and start to shift into migrating content. I'll be coordinating that work through GitHub issues, currently hosted on the swift-org-website repository, although I hope to have a dedicated docs repository to host issues and track the work of migrating existing content as we go.
You can see some of the initial porting work at #1201, which is coordinating updating content with the Swift Server Workgroup and Ecosystem Steering group.
In general, I've been carefully wrangling issues related to general documentation with the documentation tag in that repo.
(My hope is that we'll get the new repository established, migrate the issues related to general documentation vs. the Swift.org website to the new dedicated repository, and build up from there). The repository is expected consolidate and host a variety of content, as well as the scripts to support the static hosting with swift.org, formalizing how we're hosting to the subdomain "docs.swift.org".
That's a big answer for a comparatively short question, but hopefully shares both the original answer and provides some insight into how we're expecting that answer to change in the coming year. I completely agree that the documentation story could be notably better for Swift, and I'm actively working to enable that.
If you (or anyone, really) is interested in helping with new content, migration, or updating existing content, please reach out - there's a number of folks, both in Apple and within the broader community, that I'm coordinating with for improving specific topic areas.
10 Likes
Hi @FahadBuilds,
The first link you posted is to Apple's distribution of the documentation for the Swift standard library, which is implicitly imported and available for all Swift code, as evidenced by the main heading "Framework > Swift." As @MinerMinerMain points out, the standard library provides some basic functions and types which are broadly useful for writing code in Swift.
Since the name of that module is Swift, it seems that Apple has considered the page to be a logical place additionally to include a very quick introduction to the Swift programming language as a whole, links to documentation for other modules that are distributed with Swift and always available (such as the concurrency and regex modules), and links to some other topics related to Swift programming and Objective-C interop.
Note that Apple's distribution of the standard library documentation will include extensions to Swift standard library types that aren't available on non-Apple platforms.
The second link you posted is to The Swift Programming Language, which is a book that tries to give a (fairly) complete overview of the language. As the language continues to evolve, there's bits and pieces that are not as up-to-date as is ideal, but a lot of effort goes to keeping it actively maintained.
The book used to be hosted on Apple's website too, but (as others have described) it's now hosted on swift.org as part of organizational efforts to make the open-source documentation for the open-source language hosted on the open-source project's website.
However, I suspect the reason you're asking the question doesn't actually have to do with the infrastructure of the open-source project and ongoing efforts related to documentation, but rather asking for pointers about where to start learning a (very cool, in my opinion) programming language. So here's a good thing to know: since the standard library is integral to the language, it's not necessary to figure out the difference in order to get started with Swift.
There are many resources other than the official documentation which may be more suited to learning, but if you're looking for a first-party starting point, I'd recommend reading (parts of) The Swift Programming Language. You can always consult the standard library documentation for details of particular types and functions as needed, but it's not really meant to be read cover to cover (indeed, it's not a book, so there's not even a metaphorical cover, and no matter where the standard library documentation is hosted in future, I suspect that won't change).
2 Likes
Thank you. Actually the reason I asked is a bit of a long story
I first wanted to learn how to search docs.swift.org but I realized I couldn’t. (Related: How to search the online Swift documentation? , How is the 'search' feature of the generated documentation sites supposed to work? )
So I ended up adding this google search to my bookmarks whenever I wanted to search how to do something in swift “site:docs.swift.org/swift-book” which works for some swift code like guard (which is explained here Documentation ) but one day I wanted to search how reduce function works so I tried my little bookmark trick but didn’t find a link that explained how it worked, so I opted for a regular google search which brought me to the apple documentation, which I was confused by because reduce is a swift function not a swiftui function so I thought I’ll find it in swift.org which is I why I posted here.
1 Like
Thank you for the detailed breakdown of where things are at, as well as all the work that’s in progress regarding improvements to the documentation landscape. I’ve read the proposal and I do love the sound of a more centralized “hub” of sorts for documentation, though I will say it reads to me as a bit conservative with regards to the level of centralization. I’d love to help out in any way I can be useful to the effort. And I would like to share my view of the documentation/info situation as I’ve experienced it over the past year. I apologize for the length, but I have a year worth of thoughts on this xD
I’ll note that I’m new to comp sci, having started self-teaching fundamentals a couple years back, then Python, and a few other languages since. I started learning Swift/SwiftUI/Cocoa/etc only a year ago, but in this case I believe it gives me unique perspective on how bad the docs and navigation is for Swift noobs such as myself at the start of 2025. From that perspective, I can say confidently that this level of fragmentation is pushing people away from the language wholesale.
I’m so confident of this because it’s done that to me a few times already. Having the docs on even basic types torn to a dozen shards and strewn to the four corners of Earth with no breadcrumbs, no paper trial, no links, nothing to tie them together? That made learning Swift a grueling process for me. Especially having started with the Apple Developer site and docs there, and getting steered to SwiftUI as if everything else had been 6ft under for a century. It was so frustrating at times that I took numerous breaks from Swift and macOS stuff, feeling stupider every single time.
I’d go learn my way around completely different language ecosystems in between rounds in the ring with Swift. I’d go build something in a new web framework to learn it, or try C#/F# and fall in love with F# waaay too much, or learn Java/Kotlin and build a Swift parser/lexer to try and figure out what I was missing (this did help a lot). I’d feel confident again until I got to another documentary dead end (or three) that seemed to lead nowhere else. I got used to “okay, maybe I can do this project instead, and maybe I’ll run into another completely new place that has more info on what I needed to know here”.
The docs/navigation situation here is just that bad. Other langs have centralized, thorough docs that anyone you asked could point to by heart. Docs you could easily find with a quick web search. They had curation for important community/platforms stuff (eg central package manager/index). They had alternative resources for various accessibility needs. And they had the most important thing, consistent ties between the language and its own usage on any “Home Platform”. Often displayed proudly front-and-center, anywhere and everywhere in the “bog standard” official docs that it could be relevant to see the other side of something.
With the Apple docs especially, it’s the opposite of that. A lot of what you need to know seems so obscure or hidden so far, or broken into a million pieces in a million places, it just reads as intentional. It starts to feel like it’s meant to confuse outsiders, to keep them from digging in deeper than “baby’s first SwiftUI frontend hitting two endpoints”. Even now, a year in, knowing my way around at this point (why I’m actually starting to talk a bit lol), I still feel like I’m paying my dues at a plant/trade job anytime I start exploring a less-familiar arm of the ecosystem. That’s partially due to other AX issues with docs and platforms that I’m finally working on, but also just that knowing all the places to look doesn’t mean any info is there. Or for lang/apple frameworks/packages that directly compete with others, it’s often hazy what the point and trajectory of each is, so I’m always diving into source instead of reading a FAQ that should be there already, endless friction.
Tbh, if I wasn’t so stubborn, or if I hadn’t eventually found the apple doc archive, a choice old book or two, all these different orgs across GitHub, and some choice newsletters/blogs from some awesome devs, I’d have given up on this months ago and forever thought local macOS apps were too difficult for me to figure out, and that Swift was useless for even the simplest things. I’d be writing F# and JSX and leaning back into C++. I’m glad I stuck it out, eventually got comfy, and found out how awesome Swift is for my use cases, but I feel like Swift is losing a lot of people who can have their needs met by JS/Python/etc much more easily and don’t care that it won’t work right in Safari.
I guess the tl;dr is: I would argue even more centralization of docs is better, and that the most important thing is a full roadmap of the ecosystem that’s prominent everywhere possible. A roadmap including the amazing (yet buried in archives) implementation and programming guides that are so incredibly helpful, if you get lucky enough to find them. I know that’s more an Apple thing than a Swift thing, but somebody needs to let those out of the Cocoa-closet. Let the next generation see how adorable the message passing syntax was in Obj-C. Keeping that hidden is a crime, imho xD
3 Likes
A few days ago I started a discussion with @Joseph_Heck , mirroring similar thoughts; while still in its infancy, one of his suggestions was setting up a Webex for anyone interested in contributing, brainstorming, etc. If you or anyone finds interest in this idea, let us know!
There are a lot of plans, proposals, and work happening, but the lack of manpower is a real barrier currently. If you are interested in helping, don’t hesitate reaching out to @Joseph_Heck .
P.S. if you don't mind, I have a question for you and anybody who wants to share their learning experience.
- What official documentation did you consult, if any? (Swift.org, Apple developer website, WWDC videos, Swift Evolution proposals)
- How accessible did you find these resources?
- Were you ever overwhelmed by the language and/or terms used by said resources?
1 Like
I’d be more than happy to take part in a call on the subject. And yeah, I’d love to help out. I’m just working on personal projects lately, so I’ve got some time to spare regularly, especially for something I care about a lot. I’ll send them a message tomorrow.
And as far as the other questions, definitely. Though I don’t know how much detail you’re after.
I started out referencing the Apple Developer Docs, through Safari or Chrome via the Apple Developer website, or via Dash.app (for macOS). I learned early on that some key details can be found in WWDC videos, so I’ve been watching/reading (ie transcripts) those a lot as well, though less so recently.
For a while I wasn’t aware that Swift.org had more info on the language than Apple’s docs did, as silly as that may sound. I also had no clue that much of anything existed in the open-source side of Swift.
I eventually realized I needed to see implementations, as the “magic” of the platform SDKs was way more than I could decipher. I’d only found beginner-level resources elsewhere, so I looked into SwiftSyntax (as well as SourceKit-LSP, etc) after seeing talks about SwiftSyntax on YouTube that mentioned open-source. That was immensely helpful, and led to building that lexer/parser to at least figure out the language. The prep for that led me to the Swift.org book by way of the lang-spec-but-not-exactly at the back. It was a lot more complex than I’d imagined, but I had fun learning formal grammars, and within a month I finally had an accurate way to play with the language in my head. That was huge.
I then started looking into the Swift.org ecosystem and found all the cool stuff for server-side. I just started going through source code and re-reading sections of the Swift book, re-reading Apple Dev Docs, rewriting old projects, and pretty quickly got the hang of things.
The last major resource was the Apple Dev Documentation Archive, which I’ve been reading more and more of since I got the hang of how the Obj-C runtime works and found some ways to make my brain deal with the selector syntax w/ multiple args but not chopped down. I would have no clue how to use half of the platform SDKs without those Cocoa and Obj-C era guides. I find those incredibly easy to learn from.
I think it’s the depth and detail of those old guides, and that they tend to include historical background and motivating problems to start off. That sets the tone and gets me thinking about the potential structures from the start. I like to kinda think about how I would build something before I hear how it’s actually done, and having those intro bits is perfect for that. Then I just need enough of the details, whether from docs or source or built-up knowledge, to build the whole machine in my head and play around with that a bit. Those old guides are great in a lot of ways, though not great for TTS or navigation. Better than the modern ones, but not super great.
Now, as far as accessibility issues, they differ per source, but boil down to three categories for me. Discoverability, making every TTS choke or spaz out, and the formatting/presentation. There are a lot of approaches I’ve considered, but the one I’ve been working on for a month or so now is just a better TTS and Reader View setup with proper integrations to key apps, and some nice parsing, classification, and syntax awareness, so that I can just simply clone something down, open Xcode, and know that I have Swift’s own tooling in the background parsing a little AST up for me based on the open buffer, walking and grabbing pertinent info, finally popping that into structures more fitting for describing, say, the blocks of code in a file to a human such as myself, than to a literal lexer.
I would rather hear “The open file, whatever.Swift, features this and that, yada yada, would you like to hear a block by block description?” than get the literal, and often mangled (no pun intended) transcript of the file line by line at whatever barely-configurable speed the app decides that day… I want to hear the blocks described at an intelligible pace and effortlessly build that up in my head, not hear two jumbled lines of source code and then have it crash.
Same thing for the docs in literally every tech ecosystem lately. Three columns in the layout, but two are for nav on opposing sides of the layout, and then the content is just an infinite sandwich of two sentences between each pair of code snippets. Unreadable for me, it’s literally painful. And the snippets just become a garbled mess in TTS, usually crashing any existing solution I throw at it.
2 Likes
Thanks for the thorough reply. From reading your response, I get the understanding that Swift failed to distinguish itself as independent of Apple's closed-source software? Have you checked out the Swift Evolution Proposals already? As they are the most formal part of Swift's documentation, including motivation sections, future-direction sections and general implementation details. As for the accessibility issue, I would formalize the issue and potential ideas and provide it as feedback (separate post with the site-feedback tag), perhaps mirroring it in your message to @Joseph_Heck .
1 Like
Oh, yeah! I found the Evolution stuff (proposals, pitches, etc) pretty recently, and I LOVE those. I need to dive deeper into those, but as an example, the one on Approachable Concurrency was a great read. I wasn’t super hype on the changes at first, but reading that made the benefits super clear and convinced me. Having them on GitHub where I can grab and reformat the file as needed is excellent.
And yeah, the lack of either differentiation, or coupling, is the issues. Like, this morning I went to check out DocC to understand it (and its formatting/outputs) better.
So, I Google’d it, as you do. Top results are evenly split Apple/Kodeco/Swift. If I grab the Apple result < Writing documentation | Apple Developer Documentation > I get the initial impression that this is an Xcode feature, there isn’t much documentation on it, the overview is kinda meh, and there’s a tiny link to Swift.org there at the end of a paragraph that I will forget was there after I click through the few articles there.
But if I select the Swift.org result to start with? https://www.swift.org/documentation/docc/ Well, it’s the same meh overview, but it’s immediately clear this is a tool of the Swift ecosystem. We’re off to a 10x better start before even hitting the overview paragraph. It’s also clear that there’s very thorough documentation here, all organized into better (imo) categories, so on and so forth. The Swift docs on DocC are the place I would want to start, and then I would easily find out that Xcode can do the same stuff too later on when I can just intuit whatever quirks are there as I try it out in the real world.
It’s hard to break the habit of going for the Apple Docs/Dash.app, newbies are likely to go for those first anyway, and Apple really tries to hide that the full, better told, story is always elsewhere. It can shift either way, but that’s the main thing that needs to shift. More of a bifurcation that forces people to go find even the basic lang docs, or a proper (and mutually beneficial) coupling that leads people smoothly to, and around, the Swift side of things, instead of trapping them in “oh, nah this is just an Xcode feature, nothing more to see, don’t worry about it…”
And totally, once I get a model for DocC and the site, I’ll start a more formal post on it, then eventually a proposal/pitch for “Alternate/Accessible Outputs for DocC” or something after discussions and whatnot.
1 Like