Hacker News Reader

Comment by kklisura | Hacker News Reader

> 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.

View on HN

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.

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

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.

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!

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.

Reply on news.ycombinator.com