Improving the User Experience at the Documentation Archive Index

My feelings is that adding another page is a stop-gap solution to an immediate problem and that it would ultimately be phased out when addressing the core issues.

I still feel that it's perfectly fine to do it as a stop gap solution and believe that the timescale for it to be phased out could possibly be measured in years.


If we go back to the original problem statement:

visiting https://docs.swift.org/swiftpm/ shows an error, when ideally it should provide a clear landing experience that orients the user and directs them to the documentation modules and tutorials available in that archive.

I feel that the root cause of that issue is the need for a leading "documentation" path component which—as far as I know—is required by Docc Render to know what type of documentation page is requested (if it's a tutorial or not) so that it can load the right resources and put together the page. If that path component wasn't required then the https://docs.swift.org/swiftpm could be the page that's on https://docs.swift.org/swiftpm/documentation today and the documentation for its modules (for example "PackageDescription") could be https://docs.swift.org/swiftpm/packagedescription.

Additionally, if we look ahead—at what's intended but not yet implemented for combined documentation archives—when it becomes possible to pass a catalog to the merge command, then the documentation that's currently at https://docs.swift.org/swiftpm/documentation/packagemanagerdocs could become the landing page for the combined archive (which without the "documentation" component would be https://docs.swift.org/swiftpm) with the "PackageDescription" and "PackagePlugin" documentation having their own sub paths (https://docs.swift.org/swiftpm/packagedescription and https://docs.swift.org/swiftpm/packageplugin).

I don't know how much work it is to change DocC Render to not require a leading "documentation" component but this has been an issue for 5 years now.


My personal vision is that DocC would transition to fully static HTML files as the default output format, that deploying to a different location would be as simple as moving the files there, and that renaming a path component would be as simple as renaming a file/directory.

I made some progress on this last year and DocC can now (as of the 6.3 release) emit a static HTML representation of the page's content for environments that don't run JavaScript. As mentioned in the original pitch, one natural next step would be to add a small amount of CSS to improve the reading experience; with the goal of looking exactly the same as the DocC Render single-page-app version. I've been finding a little bit of time to explore this but I'm still not ready to even open an early work-in-progress (draft) PR or to pitch the idea with more details here in the forums.

2 Likes