Cabal website

[Bardur Arantsson]

(Sorry for the duplicate, forgot to send to the list.)

On 2018-06-17 17:37, Imants Cekusins wrote:
>> doesn't seem to be any particular reason to
> require JS for basic functionality on a documentation site.)
>
> Js is widely used these days. E.g., ReadTheDocs use Js [1].
>

AFAICT this is only for progressive enhancement, NOT basic "can I read
the text of this website?" functionality. That is the point I'm trying
to make -- there's no need for JS for the basic rendering of a text
website. (However, it's fine to use JS to *enhance* the existing text
website with non-essential, but nice functionality. For example, I
believe ReadTheDocs uses a bit of JS for searching the docs so that you
don't have to have a server do that. That's fine because it's
non-essential.)

> Users without Js in the browser may be redirected to a static html
> version of the website.

... which has to be written and maintained separately. So now you have
*two* sites to maintain.

This is why I hinted at using a build-time step to generate static HTML
and re-hydrating the page from there. Please read up on

	ReactDOM.hydrate(element, container[, callback])

if you don't know what hydration/re-hydration is or does.

>
> This version uses the material design [2] concept. CSS - although
> minimal - came with the library which allowed for faster coding time,
> focusing on the content and functionality.
>
> For someone with basic React knowledge the website is easy to maintain.
>

I'm sorry, what's the relevance of this? Documentation written in Sphinx
is ReST or Markdown (which doesn't even require *any* programming
knowledge) and *surely* the content is the primary thing for a
documentation site?!?

(Just FYI, I do know React very well up to and including having
implemented a complex SPA with server-side rendering for the initial
page load. Granted that's with Scala.JS + React, but it's not
substantially different from "plain" React+JS.)

I also know about all the arguments in favor or a SPA-style, so please
spare me the lecture.

> SPA arch allows for faster navigation between the pages. Client side
> rendering frees up the server.

Re-read the bit about hydrating the page from a statically built version
of the page. You have to figure out how to handle sub-pages and links
properly, but this is all doable at build time.

However, the complexity of doing it right is high enough that I don't
see the point over just using e.g. ReadTheDocs, plain Sphinx or whatever.

>
> The content largely follows the content from the existing website, with
> an attempt at improving content organisation and navigation.

No comment.

Regards,