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.
But other than that, yeah, you don't really need JS.
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.
Client machines are powerful enough now to do a lot, e.g. to scan a full-text search index packaged as a static file.
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.
> 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 , and not implementing feature because "Vue is bloat" would be an example of stupid light software.
My grandmother knows how to (and does) use the former. The latter guarantees I'll always have a job.
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.
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).
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...?
I found that via web search, but I couldn't find a demo anywhere online...
Sounds to me like you build that documentation using the SwiftUI-like DSL, but it is distributed in the DocC package.
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.
Which seems to be the case.
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?
All the HTML page does is load the JS application, and tell you to get fucked if you don’t have js enabled.
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.
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.
If a new tool doesn't work with that setup, nobody will use it.
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.
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.
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.
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.
My understanding of static webpages is that there's zero processing happening server-side. "Basic URL rewrites" counts as processing in my book
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.
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.
I hope that Jazzy keeps going.
I suspect that GH will end up integrating DocC output into GH Pages.
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.
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.
Anyway, I suspect there’s a reasonably good chance for GitHub to pick this up eventually as a feature for Pages.
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.
Er... GitHub Pages only serves content over IPv4. So is completely unusable for large portions of the world.
Which isn’t a bad thing if this is MVP1, and I do expect improvements in the future.
For every step forward they take, they take 2 back