Use cases for combined documentation of multiple targets in Swift-DocC

versioning does not guarantee that docs will be compatible. in order of increasing likelihood:

the last two items are way more common than many people realize.

this is correct, and has already proven to be a major problem for the swiftinit.org docs. doing a back-of-the envelope calculation for swift-syntax, which has a ~60MB symbolgraph and about 500 release tags, would require approx. 30GB in storage! just for one package!

diffing symbolgraphs would first require the generated JSON to be stable, which it currently is not.

diffing symbolgraphs is also incompatible with text compression, which is currently our most effective means of compacting symbolgraph data. it would also require the JSON to be pretty-printed (right now it is emitted in minified form) for line-by-line diffing to be effective, which would further balloon the file size.

Biome has an application-specific stable symbolgraph format which is VCS-friendly and yields an approx. 8x improvement in size when uncompressed, and 2–3x compressed. but this is not sufficient (yet), because we would need an improvement by a factor of maybe 100x for long-term storage of versioned documentation to be feasable.

Thanks for all the replies so far. They've both highlighted a few new use cases and brought attention to some important details for other use cases which is exactly the outcome that I'd hoped for.

It makes sense as a next step to continue with a more technical discussion about how to build this. I have more thoughts about this and am writing up a longer post with more information. I'm leaning towards posting that as a new topic to separate the technical discussion from the use case discussion. If you have more use cases for combined documentation of multiple targets, please continue adding them to this tread/topic.

5 Likes