Apple's DocC is excellent, but unusable for open source projects | Hacker News Reader

Apple's DocC is excellent, but unusable for open source projects

jessesquires.com

89 pointsingve84 comments

> DocC creates a Vue.js web app

This is the main problem with web that people are raising. Something as simple as documentation, that obviously should be a collection of static pages, is now a web application.

You don't need React, Vue, Angular, Ember, etc. What you're building now might not be web application.

Wait, what? What do they need it for?

To a boy with a hammer everything looks like a nail, I guess.

Interactive Tutorials? https://developer.apple.com/documentation/docc/building-an-i...

I found that via web search, but I couldn't find a demo anywhere online...

The tutorials are written manually in a SwiftUI-like script. It's a totally different thing from the docs auto-generator.

Thanks for clarifying, but are you sure? On the very page I mentioned, there's a link at the bottom: "Distributing Documentation to External Developers" and on that page it says: "Share your documentation directly with Xcode users or host it on a web server."

Sounds to me like you build that documentation using the SwiftUI-like DSL, but it is distributed in the DocC package.

Search? Interaction? Collapsable sections?

It's 2021.

None of these require a framework.

We don't use frameworks because they're required, we use them because they make dev lives easier and provide some common ready-made structure and functionality.

Strictly speaking, nothing ever requires a framework: after all, any framework is just code - and you could always write vanilla code to achieve the same functionality (up to re-implementing the whole code of the framework yourself from scratch).

This comment does nothing except state the obvious. ;P

The parent I'm responding to listed very simple examples that in no way necessitate a framework; of course frameworks can be useful for larger scaffolding and the like.

Where exactly do you think you're commenting...?

Rust has all of them with vanilla JS. The code is clear and easy to understand, and could be reused by other people easily. Here's an example: https://doc.rust-lang.org/std/vec/struct.Vec.html

There is no way anyone in their right mind would call main.js[1] easy to understand. It's basically complete chaos. Guillaume is making a good effort to clean up this inherited code slowly, but the interactions are still kind of broken and will be until this code is rewritten in a sane pattern such as MVU. FWIW, I have been working towards this for the past year.

[1] https://github.com/rust-lang/rust/blob/master/src/librustdoc...

Looks easy to understand to me, it would be better if it was set up as modules instead of a single file full of IIFEs but it looks pretty good as is.

You're right, as a whole it's not trivial. I remember reading the search part and found it not particularly hard, but I missed the big picture. Thank you for your work!

>Rust has all of them with vanilla JS.

Which is neither here, nor there.

Since JS is required for those features (in the absense of a dynamic server backend), who cares whether it's bundled Vue.js or some hand-rolled vanilla JS?

I'm sure some care. I'm not sure many care, and I'm even less sure that they have any valid reason to care besides a knee-jerk "bloat" reaction.

There is a quantitative difference between a folder with some HTML + other assets and a project that requires a specific v8 runtime wrapper and its own build pipeline to generate the aforementioned artifacts.

My grandmother knows how to (and does) use the former. The latter guarantees I'll always have a job.

It's a documentation generation tool whose only goal target is official macOS development enviroment, on which all of this is handled automatically via the "compiler" bundled in XCode.

It's not some generic tool handed over for random projects to write their documentation on...

But even if it was, setting up a build pipeline is trivial for developers including grandmothers who code (it's not intended for their non-coders, whether they are grandmothers or not). Most teams already have similar pipelines for their documentation anyway, whether it bundles JS or not, and are already processing it with Node (e.g. JSDoc), Python (e.g. Sphinx), Java equivalents, and so on.

If you look at the chain of comments, I'm saying that you can do with vanilla JS what you can do with Vue, so you don't "need" Vue. You're free to use it of course, but it's not "necessary". That was my main point.

> I'm even less sure that they have any valid reason to care besides a knee-jerk "bloat" reaction.

I totally agree! Especially if the team is already used to Vue or React or whatever and it will help them produce a higher quality product than going with something they don't know. I do value light software, but not to the point of stupid light [1], and not implementing feature because "Vue is bloat" would be an example of stupid light software.

[1]: https://www.arp242.net/stupid-light.html

collapsible sections are possible using css only, or using the details tag (not even css needed). As for search, you don't need a framework for that.

Actually this has existed since forever, back in 2000 that would either be a Java Applet or DHTML.

The Windows 95 ".chm" help pages [1] were basically HTML pages, displayed in an application embedding Internet Explorer. IIRC this lead to login exploits (since the login screen was able to show help pages).

[1] https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help

Microsoft Compiled HTML Help (.chm) has been the bane of all that is good and true ever since 1997.

That doesn't make it better. We should be realising the mistakes of our past and improving with time

From my experience, web developers don’t recognize their mistakes, they dig deeper and deeper holes for themselves.

Before that we would have had lovingly troffed manuals, checklists, man pages, binders, and libraries of books sitting in our spacious cubicle. Embrace tradition imo!

Maybe I'm wrong, but vue.js is just frontend js. So in theory it can be used in pair with a static server on backend side. So the problem here is surely not vue.js

IMO, search is a pretty significant part of docs and I haven't seen a good way doing that without either javascript or a web server.

But other than that, yeah, you don't really need JS.

Rust's documentation uses javascript for search but it uses no js framework at all. IIRC the normal experience works without any JS. In fact it doesn't even use any traditional js tooling, allowing people to contribute to rustdoc without having to install npm.

> allowing people to contribute to rustdoc without having to install npm

In the meanwhile, the crates.io team doubled down on Ember to attract front-end developers while presumably alienating a lot of other potential contributors.

Recall that cargo and crates was built by one of the Ember founders, Yehuda Catz.

Were they? I don't see wycats among the crates.io contributors on GitHub. He did contribute a bit to cargo in 2015, though.

The crates.io website is weird, it seems out of place and not at the same level as the other part of Rust's ecosystem.

You can just pass the query to an external search engine , adding a `site:xxx` restriction.

Every time a site has done that I immediately go back because the experience sucks so much.

Better than most site search engines, which I admittedly a pretty low bar.

A web app (as in SPA) can very well be a bunch of static files. I once wrote one at work, served off S3.

Client machines are powerful enough now to do a lot, e.g. to scan a full-text search index packaged as a static file.

I read that whole article as "Github is unuseable for open source projects."

Seriously I get that people like Github, okay. But the way everybody is rushing to hand Github a monopoly not just on git hosting but the entire open source workflow is terrifying.

If you use "monopoly" in the same sentence as "Apple" and somehow fail to conflate the two, humanity has truly lost all hope.

Aren’t all the problems solvable with a few scripts? The complaint seems to be that the archival format isn’t directly compatible with GitHub pages, and it’s stored in an odd folder, but should be possible to copy and extract out into any format using a script.

Not if the documentation is shipped as a web application which dynamically generates incorrect urls you have to rewrite on the server side.

Which seems to be the case.

Doesn't look like it, see https://github.com/JosephDuffy/DocC-netlify which is the example linked in the article. The author treating the archive as a folder with static files in it, and using the URL rewriting DSL to do full service.

> and using the URL rewriting DSL

That’s exactly the issue outlined in the article.

Now how do you do that if you don’t have a handle on url rewriting? What are your “a few scripts” going to do exactly?

Pull the HTML and CSS out into a Jekyll layout.

What HTML and CSS? It’s a giant web application, are you goings to crawl the entire thing using puppeteer to extract the content then make up pages and synthesise links?

All the HTML page does is load the JS application, and tell you to get fucked if you don’t have js enabled.

Ok, last comment, not sure I want to argue about this. It looks like an application, but it's not. It's a bunch of HTML, CSS and JS packaged in a specific way (using its own spec), but it's not an executable. It's just arcane. It can be opened and expanded in the same way that a .epub book can be opened and hosted on a static website like GitHub Pages. It's not obvious or easy, but it can be done.

Apple chose a packaging format, and they packaged it. It's not an executable. EPUB is a closer example. Can be opened, can be parsed, can be re-packaged to whatever format anyone wants.

The content of the rant is stupid, in fact, if you read this post, DocC is "unusable," with "github" and the specific workflow of the author, not specifically with "open source" projects.

But, that being said, there are countless documentation from code formatter, I don't really see what particularity DocC has to be considered as excellent.

A very large number of open source projects use a workflow similar to the author: Source code on Github, documentation on Github pages.

If a new tool doesn't work with that setup, nobody will use it.

There's also a large, and probably growing number of open source projects hosting documentation on Netlify/Vercel. Somebody's definitely going to use it, and if it has enough other advantages, people will notice and migrate. And GitHub might one day support path-based SPAs, it's old news at this point. I still remember GitHub Pages being an https holdout for many years.

In summary, the documentation tool is no good for open-source projects because it doesn't work with a non open-source website?

it doesn't work with any kind of static web hosting which is a shame given that it's all static content anyways.

The scripts could be adapted to work without requiring URL rewriting on the server.

The second complaint is about styling which currently doesn't seem possible. If you're a project of any considerable size, you probably will want your docs to be branded in some way which is not possible either ATM.

Those are certainly issues, but note that they have nothing to do with the alleged main point of the article, in that they make it unusable for open source projects. Quite the opposite, they are unrelated to the licensing at all.

I think it is a fair criticism to point out that the author seems unhappy about a non-OS website yet they somehow think this is an OS issue.

This is not about licensing.

The problem is that DocC is incompatible with the current tools that many Open Source projects use.

Sure, you could use DocC for an OS project and set up your own server to host it. It's probably pretty cheap to do that on a VM. It would require just a little bit of learning about web hosting and would require minimal maintenance.

But why would anyone do that when Github pages is completely free, requires zero maintenance, and everyone knows how to use it already?

A lot of small Open Source projects currently use Github + Github pages for hosting docs because it is such a convenient offering. If you want to use DocC, you have to look for something else.

There are many different reasons a thing can be considered unusable. This certainly qualifies. The problem isn't specific to github.

> it doesn't work with any kind of static web hosting which is a shame given that it's all static content anyways.

As far as I can tell, that’s not true. The output is completely static and just requires some very basic URL rewrites.

The Netlify config in the linked blog post (https://josephduffy.co.uk/posts/hosting-docc-archives) illustrates this quite nicely. While Netlify has some Function-as-a-service capabilities DocC uses none of that.

> As far as I can tell, that’s not true. The output is completely static and just requires some very basic URL rewrites.

My understanding of static webpages is that there's zero processing happening server-side. "Basic URL rewrites" counts as processing in my book

I have hacked "URL rewriting" on Github, bu having a custom 404 page, that rewrites the URL as a query parameter. And then in the app just use the history api to take that query paramenter and replace history without an actual reload.

I've deployed SPAs on GitHub Pages before, and you can just rename the index.html to 404.html and the site will function just as normal with no modifications.

I think that’s an arbitrary line you’re drawing. Every webserver does some URL rewriting, otherwise you wouldn’t be able to to use /docs, /docs/ and /docs/index.html. The difference is just that this requires some more custom rewriting rules to facilitate being a single page app.

I personally even disagree with that architecture, I think it’d be better to pretender the content for all pages (like, e.g., Gatsby does) but I wouldn’t call it not a static page.

The problem here is GitHub Pages doesn't support path-based SPA, i.e., it doesn't support rewriting non-asset URLs to site index. I won't argue for or against using an SPA (without SSR, too) for documentation, but this is certainly one of the most annoying limitations of GitHub Pages in 2021, generally speaking.

It's a hacky workaround, but by naming your HTML file 404.html it functions just as a regular SPA supporting webserver would. It does send a 404 where a normal webserver would send a 200, but it doesn't cause any problems from my testing.

Oh wow. Don't do this.

I have noticed multiple times that when I navigate to some documentation site brave shows this bar that page does not exist and whether you want to access it on archive.org. But the site below is perfectly functional.

I always thought that this was some weird server misconfiguration causing 404 even if content is available ... Never guessed it was a hack to enable SPA routing.

That sucks. I was looking forward to using DocC, but the not working with GH Pages is a showstopper.

I hope that Jazzy keeps going.

I suspect that GH will end up integrating DocC output into GH Pages.

Why would GitHub integrate DocC output? GitHub Pages doesn't have any other integrations, it's just a webspace for static content.

> it's just a webspace for static content.

that's not true. They do run sites through Jekyll on each commit. It's very possible they could add explicit support for rendering docarchives.

Static in this context means that requests by visitors have no influence on the site's content. As for Jekyll, it's a static site generator. The output is still static content.

DocC is also static. It just requires some simple URL rewriting. It could probably even done by putting Cloudflare in front of of GH Pages.

I'll have to study this a bit. If I can add a simple index.html file, one step up, that redirects into the bundle, that might work.

I spent a few hours (and asked on Stack Overflow [0]) simply trying to "see" the the output of DocC was (the web app documentation).

You can see an example (documenting an example app from WWDC) which I'm hosting here: https://xcode-docc.netlify.app/documentation/

Even to get this far, it was complicated, and really hope Apple listens to the community so we can have statically generated documentation.

[0] https://stackoverflow.com/questions/68048298/running-xcode-d...

Thanks for the example. I'm noticing a ~1 second delay for a page load after I click something. That seems a bit much.

Am I missing something? You can totally deploy a vue.js (or any JavaScript) on GitHub Pages.

Agreed. The only thing you'll miss out on are a few interactions with vue-router, basically your URLs will go from this:

    foo.com/blah

To this:

    foo.com/#/blah

The obvious reason being that without those URL rewriting rules the client would do a real HTTP request for "/blah" and problems ensue. Note that the problems won't actually occur until after the user tries to refresh the page or similar because the entire URL bar is being hijacked by window.location management.

I wish we had documentations in the form of man-pages even with diagrams as ascii art, and then everything is readable, searchable, highlighted, ...etc from the terminal. I don't want to pick my hands off my keyboard and pull the mouse (or touchpad, or using a thinkpad nip) just to view, read, and browse the docs.

Is setting up a (free) Netlify site really such a big barrier to entry? GitHub really has the community spoiled with their big bundle of free services.

Anyway, I suspect there’s a reasonably good chance for GitHub to pick this up eventually as a feature for Pages.

When the alternative is a set of statically generated HTML pages that can be uploaded anywhere, yes.

It’s still just statically generated HTML pages (+ some client side JavaScript). It only requires a webserver with a minimal amount of configurability for URL rewriting and redirects.

But why require URL rewriting?

There's no excuse for the need.

It's not about github. github is just the real world and most visible example, but the problem is general.

For most of my own small projects the docs are nothing but the README.md, and if the only way to make better docs required setting up a web server for each one just to host it's docs, they never will be more than the readme.

It's completely unreasonable to require a dedicated server to host some documents, which in themselves wouldn't and don't require any such thing.

Sounds like a good use case to support natively via cloudflare workers / their tool wrangler; which makes hosting less relevant. I know cloudflare is a no-go for many, but for the rest of us it makes sense. Could probably be hosted fully on their pages too?

Seems like a good opportunity for someone to setup a https://readthedocs.org like website that works with this new format. Maybe even readthedocs could start working with it.

> Because of that, we all host our documentation alongside our projects using GitHub Pages.

Er... GitHub Pages only serves content over IPv4. So is completely unusable for large portions of the world.

I suppose there’s merit in the complaints from an OSS contributor’s standpoint, but yes, it seems like the current target market is companies with closed-source SDKs.

Which isn’t a bad thing if this is MVP1, and I do expect improvements in the future.

It sounds like they've reimplemented either Microsoft's old HLP/CHM, or epub, but badly.

“Apple product is incompatible with Microsoft service”

Apple is being obtuse as always with their massive NIH syndrome

For every step forward they take, they take 2 back

Reply on news.ycombinator.com