Documentation Overhaul (DocC)?

[roeybiran]

The Sparkle project is truly an incredible achievement and indispensable tool for Mac devs, especially indie ones like myself.

Sparkle’s documentation is great and comprehensive but I feel it could benefit from a better organization and discoverability, and I think a DocC would be ideal for this.

It will allow to include articles and API reference under one roof, with all the expected features and design which are becoming norm in the Apple community.

And just to name two examples for room to improvement in Sparkle’s current docs:

1. The articles and the API reference are spread between different “domains” each with a design and layout of its own. I find this confusing.
2. The discoverability of many topics is quite poor, many areas are accessible primarily from hyperlink spread around articles. It would be terrific to have all available in something like DocC’s sidebar.

All of this and more could be addressed perfectly by DocC, and I’d be happy to take this endeavor upon myself.

What do you folks think?

[zorgiepoo]

At first DocC didn't support Obj-C, then it didn't support static hosting, and now that it does it is kind of weird according to one author. For migration purposes, breaking existing URLs and current references to them (not just on the website) seems like a real concern.

I am also skeptical here about different domains being confusing to the point that is worth putting in engineering cost to revamp to using a different tool. Discoverability of many topics being poor, etc, is too broad of a complaint. Need specific examples of how sections can be improved and then why DocC has to be used.

The API documentation being "online" is an optional nicety, with it being referenc-able from headers in Xcode (I do not think people will think to look up setup guides of Sparkle from Xcode). I think the setup guides should really include everything most people need. As for API documentation, I don't know if this is a controversial opinion, but any API whatsoever a developer opts into using from Xcode should read the documentation for it.