Add scala-js-dom docs as submodule

[armanbilge]

Demonstration of my proposal from scala-js/scala-js-dom#766 (review).

[armanbilge]

@sjrd actually this is what I was wondering your opinion on. Do you think it's too complex?

[sjrd]

Sorry for the late reply.

Mostly, my opinion here is that I don't see the point. In other words, why should we integrate the docs of scalajs-dom in scala-js.org, as opposed to publishing them in the same way that every other library publishes docs (i.e., on GitHub pages or directly on javadoc.io)?

[armanbilge]

In other words, why should we integrate the docs of scalajs-dom in scala-js.org, as opposed to publishing them in the same way that every other library publishes docs

Because to get a nicely styled site takes an annoying amount of configuration, CSS, templates, etc.. Here we are getting a documentation page that perfectly follows the scala-js.org styling for virtually no effort.

[sjrd]

Doesn't mdoc give you a nicely styled site by default?

[armanbilge]

It doesn't, it's just a Markdown => Markdown transformer.

[sjrd]

What do people usually do when they use mdoc, then? They don't care?

[armanbilge]

Many projects use Docusaurus.

• https://scalameta.org/mdoc/docs/docusaurus.html

sbt-typelevel projects use Laika.

• https://typelevel.org/sbt-typelevel/site.html

No matter what we do, we're going to need some more configuration. May I ask your objection to this approach? It's totally valid to say, I just don't like it 😛

[sjrd]

I guess my objection amounts to "I don't like it", yes. I don't think we should special-case scalajs-dom in scala-js.org. Promote, certainly (and we do promote other libraries as well, notably Laminar). But integrate its documentation? It doesn't make sense to me. Or rather, if we did integrate its documentation, why don't we integrate that of Laminar and other libraries that users are actually more likely to directly use from Scala.js code?

[armanbilge]

Thanks for clarifying, I appreciate it!

I don't think we should special-case scalajs-dom in scala-js.org.

To be honest I don't really understand this at all. It's already special-cased by living in this org and publishing under the group id. Unless you also don't like this?

I'm not advocating we link to it or anything from the rest of the website. Given its status in the org, it seems natural for it to be styled with the scala-js.org style and under the scala-js.org url.

Or rather, if we did integrate its documentation, why don't we integrate that of Laminar and other libraries that users are actually more likely to directly use from Scala.js code?

You mean, like this? 😛

https://www.scala-js.org/doc/tutorial/laminar.html

Sorry, I really don't get it 🙂

[sjrd]

To be honest I don't really understand this at all. It's already special-cased by living in this org and publishing under the group id. Unless you also don't like this?

That is a different level. It is in the organization and its group ID as a strong message that it is the underlying DOM library that other libraries should reference if they expose DOM stuff in their API. In a sense, it's a common interchange API. IIRC you were part of the discussions when we transferred its maintenance, weren't you?

I'm not advocating we link to it or anything from the rest of the website.

Ah ah, to be honest that makes even less sense to me, actually. If we're not going to link to it from the rest of the website, why is it on this website? All parts of a website should always be reachable from the top.

Or rather, if we did integrate its documentation, why don't we integrate that of Laminar and other libraries that users are actually more likely to directly use from Scala.js code?

You mean, like this? stuck_out_tongue

https://www.scala-js.org/doc/tutorial/laminar.html

If we truly thought directly using scalajs-dom is the recommended way to learn about Scala.js, then yes, exactly like this. But I don't think this is what we want to promote as the getting started experience with Scala.js.

Sorry, I really don't get it slightly_smiling_face

Meh. I guess it's a disagreement stalemate 🤷‍♂️ We could ask on Discord what people think with 👍 and 👎 reactions to the PR perhaps?

[armanbilge]

Meh. I guess it's a disagreement stalemate 🤷‍♂️ We could ask on Discord what people think with 👍 and 👎 reactions to the PR perhaps?

I mean, if a few random Discord 👍s would change your mind we can do that ... but it does make me question the value of my (and @zetashift's) opinions as the actual volunteer maintainers :) I'd be shocked if anyone cares. My goal here is to minimize maintenance burden and get something reasonably nice. Given the length of this discussion, we've probably already failed at that 😂

At the end of the day scala-js.org is your website, if you don't want to do it for any reason whatsoever, let's close this PR and move on :)

[sjrd]

I mean, if a few random Discord +1s would change your mind we can do that ... but it does make me question the value of my (and @zetashift's) opinions as the actual volunteer maintainers :)

If I've given the impression that I don't value your opinion, I apologize. The opinion of actual volunteer maintainers has of course much more weight than of random users. I was only suggesting that as a way to perhaps resolve the disagreement between your opinion and my own. If at all, I'd like to think that it is a sign that I value your opinion as much as my own.

[zetashift]

I'd be shocked if anyone cares.

If there would be a poll on Discord, I'd imagine this result as well.
I don't really have a hard preference here tbh, I don't mind redoing the HTML/CSS for scalajs-dom. Tho I must admit this PR isn't near as bad as my initial reaction to the idea( I thought it would be a bad idea).

So the value in this PR is:

Because to get a nicely styled site takes an annoying amount of configuration, CSS, templates, etc.. Here we are getting a documentation page that perfectly follows the scala-js.org styling for virtually no effort.

If I look at this PR, it really is like a simple and lightweight solution, even tho it feels like an icky entanglement between scalajs and scalajs-dom. The worst thing happening here is removing some YAML lines no? The separation is quite clear( a git-submodule). At first I thought it'd be extra maintenance burden for this website project, but looking over it, they just share a bit off infrastructure, which isn't that bad considering they are under the same org. Scala.js users/beginners won't notice that, and for org members it less infrastructure to handle across projects.

A middleway might be to add a similiar page like the Laminar tutorial but for scalajs-dom and link to that in scalajs-dom README.

[zetashift]

Meh. I guess it's a disagreement stalemate man_shrugging We could ask on Discord what people think with +1 and -1 reactions to the PR perhaps?

@sjrd sorry for the ping, but do you think you could take a look again? Maybe a decent middleground would be doing polls on users.scala-lang.org or multiple community sites?

[armanbilge]

Sorry I've been silent on this.

@sjrd so here's the thing ... over the last couple years I've watched and deeply admired how you work and collaborate with others. Now I could be wrong, but based on what I've seen, I believe if you felt strongly about this issue you wouldn't suggest it be resolved by a Discord poll.

So yeah, I realize it's not your intent, but I do feel insulted and disrespected by your suggestion. It seems you don't feel strongly, but here we are, the volunteer maintainers. Of course we value your opinion here and and after having considered it we still feel that this approach overall makes the most sense. Our goal is to have nice documentation and minimize our volunteer maintenance burden. We feel strongly about this and it is hurtful that instead of trusting us on this one, you'd rather do something between a coin flip and a popularity contest.