Hi everyone, it's my pleasure to share the annual update for the documentation workgroup.
In terms of workgroup members, I'm glad to share that @sofiaromorales has officially joined the documentation workgroup after numerous contributions to the Swift-DocC ecosystem.
We also are very appreciative of @ethankusters, @krilnon, and @theMomax's many contributions to DocC and TSPL documentation, who decided to step down in order to focus on other efforts and give space for others to join.
The documentation workgroup continues driving efforts toward a better documentation experience in the Swift ecosystem in the following major areas:
- Ergonomics for linking between documentation. We've made progress towards supporting a human-readable alternative for symbol link disambiguation which leverages functions signature information. The 6.0 release supports writing documentation links to headings and task groups and includes refinements that make it more natural to document mixed Swift and Objective-C projects using either language representation's spelling of symbols in links.
- Linking between different targets and documenting multiple targets together. We've made significant progress toward writing links to other targets and creating combined documentation for multiple targets. The 6.0 release include experimental support for linking between targets behind a feature flag and an experimental command to create combined documentation archives. Links to other targets support all the same features as links to local pages and produce the same rich diagnostics when a link is ambiguous or otherwise unresolvable.
-
Improved support for documenting overloaded symbols. After proposing a feature in the forums to combine symbol pages for overloaded methods, the 6.0 and trunk toolchains now include this behavior behind a feature flag. Grouped overloads appear once in curation and the navigator, and can be linked to in a symbol link without a disambiguation hash.
-
Improved documentation experience on Swift Package Index. We ran a number of tests with preview toolchains to determine the impact of upcoming DocC features on packages that host their documentation on the site. Also, changes in DocC reduced the number of files and total documentation size of documentation archives significantly. The Swift Package Index now hosts documentation for more than 700 packages.
-
Added the new
docc initcommand which makes it easy to get started with writing standalone conceptual documentation not attached to a module. -
Continued updating the Swift language documentation for Swift 6 features and new proposals.
Over the next year, the workgroup is interested in developing the following areas:
-
Support documenting multiple targets, packages, and multi-package projects as a whole with links between targets.
-
Improve the readability and expressiveness of links to other symbol documentation pages and articles, for example by extending links' disambiguation syntax.
-
Explore linking between separately hosted documentation—for example, linking to external package dependencies or SDK dependencies.
-
Work towards high-level API documentation guidelines to complement the existing API design guidelines.
-
Discuss new exploratory documentation systems led by the community, such as Swiftinit.