Http4s site discussion

[keynmol]

Continuing a discussion started by Noel Welsh on twitter, hoping to discuss some ideas here and break them out into issues once we reach consensus.

What follows is a living list of concrete suggestions to improve the documentation, both aesthetics and content

Stylistic

Versions page:

• Only keep 0.21, 0.22, 0.23, 1.x

  Put "Which version is right for me" next to lineage rows

• Remove Scala 2.10, 2.11 from the table

Whole site:

• Design

  Update Bootstrap to 5.1.1 #5191

• Add Algolia DocSearch: https://www.algolia.com/

  See Add algolia search sbt/website#963 for whole process, should be simpler with Hugo (and no multilingual sites)

• Use mdoc:compile-only for most places, to avoid the rendering of IO values.

  Consider doing something like mdoc-effect: https://mdoc-effect.indoorvivants.com/ce3/index.html to separate output from the code

• (minor) formatting of code examples

  Pretty snippets are pretty. Scalafmt 3.0.0 introduces that support for scala-fenced snippets: https://github.com/scalameta/scalafmt/releases/tag/v3.0.0

• Explicit links to sections

  Perhaps I'm dense, but hopefully this can be done with Hugo (i.e. like Cats effect site does it:
  )

  This should help deep linking

Content

• Explanation what different imports do

  It's probably a hot topic in future versions of http4s, but for now it'd be good to provide a troubleshooting guide for common errors that are fixed by dsl.io._ or implicits imports, along with explanations. Hopefully that can be indexed by search engines

• Update Quick start

  My feeling is that the screen space on Quick start page is limited and very expensive, so perhaps the listing of giter8 variables can be moved somewhere further down, and instead an example of Http4s setup in a single-file IOApp with server and client would be better?

[noelwelsh]

#5191 for simple design changes.

I would also like to:

• Invert the pyramid so the most important things come first. For example, the JSON page currently discusses something that no-one uses (raw JSON) before describing the things that people will actually use. It should be the other way around.

[keynmol]

There's also a fair number of issues labeled with docs that cover a lot of previous user requests: https://github.com/http4s/http4s/issues?q=is%3Aopen+is%3Aissue+label%3Adocs

[noelwelsh]

I'm going to look at updating Hugo to the latest version.

(For the record, I will resent everything I have to learn about Nix.)

Update: I'm going to peace out on learning nix because it's just making me angry. If someone can change the hugo dependency to 0.88.1 and get nix-shell to actually recognize that change I'll rebuild the site from there.

[jenshalm]

@armanbilge I found something I wanted to check first before I continue, as it feels like a potential showstopper. I noticed that all your pages are hosted as an index.html in a separate folder, for prettier URLs I assume. Laika does not support this pattern as an auto-translation step during transformation and it's not something I could easily and quickly add. The only way to retain this structure with Laika at the moment would be to physically organize the Markdown sources in equivalent folders, too, or to delve fairly deep into Laika extension territory.

[armanbilge]

@jenshalm hmm, that's frustrating. It sounds like your idea to put the docs in separate folders would be okay though (unless this will cause other problems, e.g. with navigation?) so that at least we can preserve existing links ...

[jenshalm]

@armanbilge: Moving them into folders would certainly work and it's quick and easy to do. I'm just not sure it's ok with maintainers as it's not very convenient to work with. The extension option is there, too, but it would A) delay the PR for several days at least, and B) mean you'd have the extension plus a little test suite for it in your code base until Laika potentially supports it out of the box.

I wasn't aware people do this kind of thing and it has never been requested for Laika in 9 years, that's mainly why it's not supported, it's certainly doable otherwise.

[armanbilge]

@jenshalm I'm too new of a maintainer to give any authoritative answer, but it sounds like a little extra folder structure (although annoying) is much more tried-and-true than a custom extension in our docs project, which would be inconsistent with Ross's "few moving parts" criterion in #5192 (reply in thread). If one day Laika could support this out of the box, that would be awesome, and we can revert the original structure. If it's too annoying, we could also just burn all of our existing links (I wonder if this could be mitigated with some quickie Javascript on the 404 page to redirect or even just a kind message apologizing for the restructuring).

[jenshalm]

@armanbilge Ok, thanks for chiming in, I'll add it to the list of open question on the PR then and wait for a definitive answer before moving on. There are other open questions, too, so I'm getting pretty close to needing feedback anyway.

[rossabaker]

@keynmol has many excellent ideas here, but let me pour some cold water on one:

(minor) formatting of code examples

Pretty snippets are pretty. Scalafmt 3.0.0 introduces that support for scala-fenced snippets: https://github.com/scalameta/scalafmt/releases/tag/v3.0.0

I've been closing all the scalafmt-3.0 PRs until we regain some branching sanity (which I'll be initiating another discussion on soon). I tried running it on each branch, merging it with the previous branch, keeping ours on all conflicts, so we could proceed from a solid merge base. It was a lot of work, and scalafmtCheck failed, so I reverted to 2.x. It might be ready to try again now that it's a few patch releases deep.

[keynmol]

That's fair 👍 TBH branching is an issue for docs in a more general sense - as I understand it, adding docs for core concepts (that have changed in the 0.21 -> 0.22 -> 0.23 -> 1.0) would require 4 versions of docs for each branch to make sure they all compile?

[rossabaker]

Publishing compiled mdoc from each branch is what we've done in the past, but it complicates things with an ad hoc process. I think it's nice to have, but one good branch of docs is better than four mediocre ones if we have to choose.

[kubukoz]

Made #5416 for some extra client docs. Working on this, I felt like there should be a table of contents for a given page: consider how many headings that site already has.

Also, copyable links for the headings would be a great thing to have. They already have ids so it's just a matter of adding a chain icon or just making them clickable ("copy link address" would work just fine).

[jenshalm]

@kubukoz See #5313, once this is on Laika, page navigation comes for free.

[noelwelsh]

Added #5539 for a tutorial