Thank you! I hope the doc makes sense!
I really appreciate DocC. It is the first time I use a tool dedicated to documentation editing. It has very good ergonomics, for both the writer and the reader.
From the writer point of view, I quite enjoyed the forgiveness of DocC. Mistakes do not prevent the doc from building. Warnings help performing the necessary fixes. The doc is always exhaustive, so you can't miss the types and methods that are not properly organized yet. And you can take care of them, one after the other, at your preferred pace. Kudos to the DocC team!
You can gradually improve your documentation, and discover or tweak how the documentation is organized as you write. This works very well for me, because I need to rework my text several times until I believe it makes some sense for my imaginary reader. Links between doc comments (///) and markdown articles are super useful.
The DocC documentation itself is NOT very well organized on the Internet. I don't find it normal that it took hours and luck to finally discover GitHub - apple/swift-docc-plugin: Swift Package Manager command plugin for Swift-DocC (a boon for publishing on GitHub pages). Granted, I found it. But after I had already struggled a lot with xcodebuild and its low-level api. There are too many conflicting and overlapping documents on the Internet, with various levels of obsolescence. swift-docc-plugin is NOT mentioned in Apple Developer Documentation, and such an omission is beyond my understanding.
This is surprising, because sometimes I could really feel that the people who made the tool understand deeply my needs (this can't happen by chance: this level of comfort was clearly designed, with a level of care that goes beyond a mere checklist of features - UX expertise at its best). And sometimes it's just as if I met another team who has no clue about an important target audience in an open-source ecosystem: the volunteers (little time, little resources, a lot of good will, strong appetence for free tools with large audience). I had a similar feeling, at times, while reading this recent thread: SE-0346 and library evolution