The state of Swift documentation

Evolution Discussion
#28

This is exactly the reason to make the documentation efforts the top priority and to start it now. We need to make sure that the documentation improves as the project grows, right now there's an impression that the documentation coverage and quality don't keep up with all the changes. If we dismiss this as a priority, the state of things will only become worse in the next five to ten years. If the declared goal is to make Swift available for everyone on all platforms, the community should be able to participate in that instead of being excluded.

By "being excluded" I mean only the impression that people get when they are introduced to the project, just as @Zollerboy1 highlighted above. One obviously could answer "everything is open source, what else do you need? We should be happy with what we've got, it could have been closed source", but that won't help us attract more people to the community, maybe even the opposite. There's still the impression that Swift is "an Apple language" and I find it hard convincing people otherwise for exactly these reasons. A lot of it is more similar to "source code dumps" that Apple have been doing before they started using GitHub. I appreciate they started accepting pull requests, but this is only the first step and it's clearly not enough.

5 Likes
#29

Are you talking about documenting the compiler itself?

I agree that some of that could be made clearer. For example, I remember when I first saw the project - there were lots of comments talking about "tail allocations", but I'd never heard that term before and Googling wasn't very fruitful.

That said, there will always be some required knowledge when contributing to the compiler.

  • Firstly, you need to know how compilers work - sounds obvious, but I think that is the biggest hurdle we have today. Even if the entire project was written in Swift rather than C++ and fastidiously documented, that barrier is always going to be there.

  • Secondly, you need to know how LLVM works. It's the framework upon which the compiler is built. To put it another way - if you took a complex iOS application, and you knew nothing about UIKit, you would look at the code and be just as confused.

It might be worth getting feedback from the Google folks about this, as I think many of them were already familiar with other LLVM-based compilers. How easy is it for somebody with that background knowledge to get started with the Swift codebase? I think that's probably the most relevant question to ask when it comes to the compiler.

3 Likes
#30

I don't think any of this is stated clearly anywhere in the Swift compiler documentation. There are no links to relevant LLVM documentation there, and it's hard to say that LLVM documentation is great either. You will find a couple of introductory guides, but most of it redirects to the doxygen-generated reference, which a lot of times has either empty "No overview available" style comments, or comments that duplicate declaration names in plain English, but don't explain the purpose or give at least some examples of API usage. To exacerbate things the doxygen reference is also not searchable.

The point here is not eradicating the barrier completely, as you said it will always be there. The goal should be in lowering the barrier as much as possible and make that a priority. This will help us attract more contributors and broaden the community, which will have its own network effects as we'll have more eyes on the code, fixing bugs, adding features, and making this infrastructure more portable, or adding support for other platforms directly. This in turn will attract even more people, making the community stronger and more vibrant, ensuring that Swift as an ecosystem is viable and has wide use cases.

The spectrum of developer experience when onboarding to new complex projects is very wide, and very strongly depends on how project documentation is structured. If this hypothetical complex iOS application is poorly documented, has no references to existing resources, and partial existing documentation is not searchable and is not maintained, obviously the amount of time to get yourself comfortable with it will be very considerable.

On the other hand, a few complex iOS apps I've worked on previously had thorough description of the architecture with strict requirements on documentation coverage, and deployed documentation itself was rendered in a searchable form on CI for every commit. Even though architecture decisions made in those apps were somewhat sophisticated, I was able to make my first contribution in the matter of hours, not days as opposed to undocumented app codebases. Similarly, I witnessed that junior developers, who had very little experience with UIKit, enjoyed the onboarding process and learned a lot or got references about UIKit thanks to the detailed app documentation itself.

6 Likes
#31

@Max_Desiatov These are all good points, but I think ideas for improving compiler documentation are straying a little from what this thread is about: which is the experience for developers writing Swift code on non-Apple platforms.

Perhaps it is worth moving the compiler discussion to a different thread.

5 Likes
#32

I don't think that these topics are currently divorced enough from each other to discuss them separately. It would be great if they were, but one of the points in the original post was about documentation generated for the standard library and Foundation. The former uses GYB, while the latter is mostly built with the build script stored in the toolchain repository. Neither of those are well documented, and if they were, it would be related more to the compiler and the toolchain/SDK infrastructure in general.

Or, similarly, there was a suggestion above to use swift symbolgraph-extract to improve documentation for user libraries, but that tool itself is a part of the toolchain and is not documented.

3 Likes
#33

In addition to what others have posted, here is something from my observation, along with a suggestion for improvements:

  1. Documentation of Swift Package Manager is scattered in 2 parts on swift.org: its API documentation is grouped in and accessible through the "Documentation" page, and the more tutorial-like part is grouped in the "Projects" section. Neither one provides links or references to the other.

  2. I think the Language Guide part of The Swift Programming Language is a fantastic resource for first-time learners. My only problem with it is that it omits some important information. For example:

I suggest that going forward, we should start requiring all new evolution proposals to include an evaluation on how documentation should be updated (when the documentation is closed-source like The Swift Programming Language book), and/or actually updating the documentation (when the documentation is open-source like the "docs" directory in Swift's repository)

14 Likes
#34

Definite +1 on this. I feel like documentation, especially for a new language is going to be a must, and if everyone just documents their own stuff, it'll be no work at all. It's the existing things that are going to be hard to document. The sooner we can get change to happen, the easier our work will be.

Also, I feel that the documentation of an open source language is just as important as the language itself. We all want the language to be easy to use for both beginners and power users, and you can only get so far with the language syntax. We need official language documentation that is reliable and detailed for both beginners and experts alike.

2 Likes
#36

@Karl is correct that my intent for this thread was to talk about improving the documentation for users of Swift. While I'd also appreciate more documentation for the compiler and related tools, I think having better language and API documentation is much more important for the Swift project.

That being said, I don't necessarily have a problem with discussing ideas for improving the compiler documentation in this thread, too. So far, the volume of posts has been manageable.

I strongly agree with this sentiment, and I think the state of the API documentation is an indicator that the impression is not unfounded.

9 Likes
#37

Imma ditto that. I've long been impressed by Swift as a language for its versatility and relative ease-of-use, and have said as much to my coding friends. Unfortunately, most of these friends still confuse Swift with SwiftUI (and by extension UIKit), mostly riding on the impression of Swift as "an Apple thing." This perception ties naturally with the squeamishness of some around the subject of vendor lock-in, for which Apple is famous.

I believe that Swift has a place on just about every platform, but when folks need to dig around on Apple sites through Apple-esque documentation that really isn't all that great just to get started using Swift on their platform of choice, it's difficult for me to ease their worries about being "locked in to Apple's way of doing things" while showing them how great Swift can really be.

So... who do we talk to to get this rolling? What direction should we attack first? Should we work to get existing docs open-sourced? Do one of us know somebody at Apple who's in charge of their Swift documentation? Do we have a public repo already? Should we work on updating and improving Swift's existing inline docs first? I'm excited to see this rolling and to help where I can, but I just don't know where first to aim.

8 Likes
#38

I also experience this from time to time; just linking to documentation about the Swift standard library points to the apple.com domain, enforcing the idea that Swift is an Apple language, which means that a lot of mindshare is lost.

5 Likes
#39

This page on Swift.org was recently shown to me by someone evaluating the feasibility of Swift on Linux: https://swift.org/core-libraries/

The page ends with:

As stated above, this project is in its early days. We look forward to working together with the community to create a great set of libraries that enable Swift to produce powerful software across platforms.

That does not instill much confidence, and is it even true anymore?

7 Likes
#40

I think what makes great a programming language are not only its features but the developer experience. Doesn't matter if your language has the coolest features and is the fastest in the world but if your are lacking of a good dependency manager, editor, and documentation, the language feels incomplete and kind of unusable, even if the language itself is very robust. Sadly for Swift historically if we talk only from the documentation perspective (as a cross platform language), feels very incomplete, and incomplete not because doesn't exists at all, incomplete because the documentation is only for apple platforms. When in the current documentation site we just see in which Xcode/AppleOS version a feature lands and not in what Swift's version, makes you think that the feature only is officially supported and only works in apple platforms. I think this one of too many reason that prevents Swift to get adopted from others when they see the language is very apple oriented.

5 Likes
#41

Preventing Timing Problems When Using Closures is absolutely not enough in the Docs. It must has a lot of concrete instruction how to use Dispatch

#42

is there a language community that you think is a good example of a language community that does these things well?

1 Like
#43

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

7 Likes
#44

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
#45

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
#46

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
#47

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.

#48

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