Over the past few years, Embedded Swift documentation has been graciously maintained by @kubamracek in the swiftlang/swift repository. As Embedded Swift continues to mature and adoption grows, we’ve identified a few opportunities to improve how the documentation is hosted and maintained:
The documentation isn't easily discoverable and isn’t hosted outside of the GitHub repository.
Contributing requires cloning the swiftlang/swift repo and navigating a long and complex swift-ci process, which can be intimidating for new contributors.
The documentation tries to cover a broad and growing set of topics—from multiple build systems to SDK integrations to language mode details—but maintaining all of this in a single location has become too much for one person to manage effectively.
To address these challenges, we’ve started migrating Embedded Swift documentation to the swift-embedded-examples repository as a DocC catalog. The initial migration ports the existing documentation with minimal changes and is already viewable on the Swift Package Index.
Documentation Layout (Work in Progress)
The structure of the new documentation is still evolving, but the first iteration includes:
[Page] Embedded Swift: (Port) Vision document from swiftlang/swift
// FIXME: High-level overview for the entire catalog
// FIXME: Should be broken out and partially moved to “Language Details”
- [Section] Getting Started:
// FIXME: Subject to large changes
- [Page] Install Embedded Swift: Installing nightly toolchains with Swiftly
- [Page] User Manual: (Port) from swiftlang/swift
// FIXME: Needs a full rewrite
- [Section] Guided Examples:
// Example-driven tutorials based on the embedded-examples repo
// FIXME: Needs more guides
- [Page] Raspberry Pi Pico Blink (Pico SDK): (Port) from swift.org
// FIXME: Needs a full rewrite
- [Section] Build System Support:
// Guides for using Embedded Swift across different build systems
// Each includes examples for both host and QEMU platforms under
// `Sources/BuildSystems/<build-system>`
- [Page] Integrate with Bazel: (Stub)
- [Page] Integrate with CMake: (Stub)
- [Page] Integrate with Make: (Stub)
- [Page] Integrate with SwiftPM: (Stub)
- [Page] Integrate with Xcode: (Stub)
- [Section] SDK Support:
// Using Embedded Swift with specific hardware SDKs
// FIXME: More guides needed
- [Page] Integrating with Raspberry Pi Pico: (Port) from swiftlang/swift
// FIXME: Needs update for modern Swift CMake usage
- [Section] Language Details:
// FIXME: Subject to large changes
- [Page] ABI: (Port) from swiftlang/swift
// FIXME: Needs a full rewrite
- [Page] Existentials: (Port) from swiftlang/swift
// FIXME: Minor rewrite to align with surrounding content
- [Page] Non-final Generic Methods: (Port) from swiftlang/swift
// FIXME: Needs a full rewrite
- [Section] Development:
- [Page] Status: (Port) from swiftlang/swift
// FIXME: Needs a full rewrite
- [Page] Swift 6.0 Release Notes: (Missing)
- [Page] Swift 6.1 Release Notes: (Missing)
- [Page] Swift 6.2 Release Notes: (Missing)
There’s a lot to write, review, and organize—and community contributions are more than welcome! If you’re interested in helping shape the structure, improve the flow of information, or contribute content, feel free to share your thoughts in this thread, open GitHub issues, or submit a pull request.
I have questions about templates / guidelines for contributors. Do you have any yet? Is that something for this wave of documentation or for after you have collected more contributions and can use those for inspiration?
TL;DR:
The answer right now might just be "Do what you want to do and we'll react to it" which is totally valid. However, if there is the possibility for some initial guidance, that'd be awesome.
More Details
Are the sections meant to be (can have a different answer per section):
Consistent with a style guide to make it easier for readers to pull out the information they want in a consistent way that is efficient for them.
More of an anthology where the personality of the individual contributors really shines. Emphasizes the heterogeneity of the space.
Templates and guidelines can both promote and inhibit contributions. For shy contributors they give them a hook in to start. For people who have something already, guides and templates might prevent them for submitting because of the distance between what they have and the guides. (Also just the idea that their distinct work will be merged can be hard enough, but that's a different topic)
I'm asking partially because I'm immediately having some audience questions. That's personally where I always start (who's reading? why are they reading? where do we (them and I) want them to be at the end of reading? How will they know that they got there?) Selfishly, I would be helped by a template or a guide to help answer my questions about where I should be starting.
For example, if there is no audience limitation in Guided Examples, encouraging contributors to put information near the top about the skills of their intended audience would be really helpful to the readers but also indicate to the writers there is no limit as long as they are explicit.
Having clarity about the audience(s) for the Getting Started guide(s?) would be really helpful. That section has to be TIGHT because starters tend to be higher anxiety than other audiences. Stricter editorial standards there probably will be necessary than other sections. That said SwiftEmbedded is HUGE. There are some pretty dramatically different hello worlds to get to and dramatically different starting places for the people who want to get there. What group is the priority?
I could go on... but that's a document in and of itself! Ha!
This are really really good questions, and I've started writing a reply a couple times this week and deleted all of them. Instead of hashing this out async over the forums, would you (and any other interested parties) be interested in an "Embedded Documentation Working Session" on the discord? We could discuss the topics you brought up here, some of other in progress documentation work, and work on the docs live as well.
if you're/anyone else is interested, is there a particular time that would work best?
Full disclosure, I plan to merge this mostly as is (barring major issues) and iterate on feedback/improvements afterwards. Generally I want to make it as easy as possible to make documentation improvements so long as feedback is addressed in a timely manner.
...and I'll add that I absolutely won't mind of any of the text that I wrote will get replaced with something better I'm now mainly trying to cover some topics that are obviously crucially missing.
I'm now mainly trying to cover some topics that are obviously crucially missing.