The state of Swift documentation

I think rust is doing great about this. One of the many things that people loves about rust is its documentation.

7 Likes

that’s a really nice website, i wish apple was as willing to put its communications expertise behind swift as mozilla is for rust. imagine if the swift website was like the airpods support website…

4 Likes

That site certainly does a lot better at selling you on the language and helping you find resources for all kinds of application domains. We could learn from that.

Everybody knows about Swift and iOS/Mac Apps, but I guess far fewer people know about the server efforts. There's a tab about it on swift.org, but it's not very prominent and the page itself is basically only about the working-group process. There's a table of GitHub links, with no description of what the repositories contain, and zero testimonials. That table also doesn't cover important frameworks like Vapor or Kitura, which anybody getting started with Swift on the server would surely be interested in exploring.

I've heard that Apple are using Swift services in production - and you can kind of infer that by the presence of Apple employees on the server working group. That would be a very strong testament to Swift's performance and reliability if it was a bit more explicit. There was a blog post recently about the AWS Lambda runtime. That's cool, but how long before that gets buried under newer blog posts? It would be nice if there was a "Swift on the server" landing page for people new to the language/ecosystem.

Similarly, we could do a much better job letting people know about Swift for Tensorflow. I guess there was probably a blog post about it once, but just looking at swift.org right now - you wouldn't even know it exists. It doesn't even have its own sidebar tab :slightly_frowning_face:

15 Likes

As an avid user of both Swift and Rust I cannot help but notice that the difference in quality (and quantity) not only differs for the official language/stdlib documentation, but for the entire ecosystems, just as much.

It's like a reverse broken windows theory is at play: having a way above average documentation for the language and stdlib itself encourages the community to follow suit and make sure documentation not only exists (at all), but actually is at the highest quality, before publishing a library.

For Rust very few (popular) crates have severely incomplete or bad documentation, as there is quite a bit of pressure to be a good ecosystem citizen.

While for Swift it's actually rather rare to find documentation (if any) that comes anywhere close quality-wise to that found for many popular Rust crates.


Swift:

The time-investment for good documentation is quite substantial for non-trivial projects. Specially if with Swift there are hardly any tools to help you: There is no first-party tool for generating docs, no way to figure out your project's docs coverage, no way for users to open the corresponding source code for a given documented item, and most importantly: there is no standardized way to host docs and no central index.

Rust:

Rust in comparison comes with the batteries included and makes it trivial to provide docs: By running $ cargo doc you can not only effortlessly generate docs for your crate, but all the documentation of your crate's dependencies, too. There is no step two. And once the crate has been published on crates.io people can access the docs via docs.rs without one having to lift a single finger. Also your crate's documentation has the same look and feel of the official docs, reducing access barriers, otherwise caused by ecosystem fragmentation. The compiler can also warn/error missing documentation (#![warn(missing_docs)]) and even makes sure all your documentation code samples still compile (documentation tests, when running $ cargo test. There even is third-party support for checking your code snippets within README.md.


"If people are unlikely to discover and consequently read my Swift library's docs, why should I bother writing them in the first place?" is a tempting conclusion, albeit a bad one. Bad for everybody.

This is in great contrast to Rust, where there simply is no excuse to not provide excellent documentation for your crate, as the additional overhead is minimal.

High standards of the language/stdlib are an influential multiplier for the ecosystem as a whole that can easily be overlooked.

41 Likes

Thank you, that was very informative. I think the way forward is to pursue something like cargo but as a swift compiler command like swift doc or swift build -doc perhaps. Maybe this is too outlandish, but building docs by default (with a disable flag of course) would definitely incentivize writing documentation.

At this point, I feel we are kinda waiting on Apple to do something about the official docs. Apple seems content on only working on new features and new things, but never wants to pay attention to the nitty gritty documentation. I feel that we could use some people working on solely official documentation, at least until it is complete. I'd be happy to do some work myself, but I don't know the ins and outs and it'll take very long.

Adding to the list of missing documentation:

^ This quote is from a recent thread on protocol self-conformance.

The differences between dynamic and static things (type, dispatch, member lookup, etc) are very important for users to understand (I myself don't understand them well), in order to have a good grasp on the language. However, they're largely missing from the Swift Programming Language book. A lot of this kind of things are documented in the git repository, but most Swift users don't come to the forums or dig through the repository for answers. Some might not even know that a repository exists. The language book is the only official resource for many users, and it would be good to have all the important information included directly in it.

7 Likes

The distinction is more salient in Swift, though--in a lot of cases, it's mostly just a performance detail, but in Swift it's absolutely fundamental to how function call dispatch occurs. You can't really understand the language without understanding the distinction. So it's not a "programming 101" concept, but it is very much a "Swift 101" concept.

14 Likes