Hi all, Re: https://github.com/haskell/cabal/issues/4013 Would https://ciezbit.bitbucket.io/cabal/doc be an improvement over https://www.haskell.org/cabal/ ? This link points to a temporary demo deployment. The app is written in React with material-ui lib.
Please use this link instead to access the demo:
https://ciezbit.bitbucket.io/cabal
On Sun, 17 Jun 2018 13:32 Imants Cekusins,
Hi all,
Re: https://github.com/haskell/cabal/issues/4013
Would https://ciezbit.bitbucket.io/cabal/doc be an improvement over https://www.haskell.org/cabal/ ?
This link points to a temporary demo deployment. The app is written in React with material-ui lib.
On 2018-06-17 13:32, Imants Cekusins wrote:
Hi all,
Re: https://github.com/haskell/cabal/issues/4013
Would https://ciezbit.bitbucket.io/cabal/doc be an improvement over https://www.haskell.org/cabal/ ?
This link points to a temporary demo deployment. The app is written in React with material-ui lib.
No opinion on the content, but You need to enable JavaScript to run this app. is not acceptable, IMO. (I believe some/many search engines can handle it these days, but there doesn't seem to be any particular reason to require JS for basic functionality on a documentation site.) Of course, if the React could be rendered to a string and build-time and rehydrated from there when loading the real page then that's probably OK. Regards,
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]. Users without Js in the browser may be redirected to a static html version of the website. 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. SPA arch allows for faster navigation between the pages. Client side rendering frees up the server. The content largely follows the content from the existing website, with an attempt at improving content organisation and navigation. Does rendering by search robots need to be verified or may we take it as most likely working? [1] https://docs.readthedocs.io/en/latest/development/standards.html#background [2] https://en.m.wikipedia.org/wiki/Material_Design
Imants Cekusins
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].
The fact that JavaScript is widely adopted makes it acceptable to use, but it is not a _reason_ to use it. I don't see anything about the (mostly static) Cabal website that motivates its use. I will discuss that more below.
For someone with basic React knowledge the website is easy to maintain.
This statement sounds like you are volunteering to create a new website, but not to maintain it. Is that what you mean to say?
SPA arch allows for faster navigation between the pages. Client side rendering frees up the server.
In this instance, SPA seems like a solution in search of a problem. There is nothing about the static content of the Cabal website that would motivate using SPA. I find the claim dubious, but let us assume that SPA would lead to faster page navigation; is page navigation too slow now? Likewise, client-side rendering may free up some server resources; is the Cabal website server-resource bound now? To my untrained eye, the motivation for the new design seems to be neophilia. That's good for an experiment, but I don't see the motivation to adopt it. What does this redesign offer to our users? What does it offer to us?
Well, I put in a full week in this version. If this website is not usable, fair enough. Let's wait for the version that suits.
I don't think this is fair to the maintainers of Cabal and the Cabal
website. You can't do work nobody asked for and then get upset if
people are unwilling to adopt and maintain the unasked-for-code.
That's like buying someone a puppy, when you don't even know if they
like dogs. Writing software anew is the fun part, the not-fun part is
the maintenance.
I've worked as a web developer for 10 years now and a SPA for what
could and should be strictly a purely static content website would
only have downsides even when you ignore maintenance. I won't
enumerate my grievances with SPAs in general or in particular for this
kind of website, Bardur and Thomas and discussed some of the issues
ably.
I appreciate that you wanted to make something for the community and
see it get used, but you need factor in and carefully consider
peoples' needs, constraints, and desires if you want them to use what
you make. I think it would be sad and a loss if this put you off
contributing to projects like Cabal in the future though.
If you're interested in helping the Haskell community and it wasn't
just about making a ReactJS website I would exhort you to check the
calls for participation on Haskell Weekly ( e.g
.https://haskellweekly.news/issues/111.html ) or to reach out to
specific maintainers on projects you care about and ask them what they
feel is needed. I'm not involved in Cabal and have no authority, but
if you'd asked me, I would've said the Cabal site mostly needed some
design and content love, but if that's a specific thing you want to
help out with then I'd say you should talk to those responsible for
Cabal.
Hope you have a good day,
Chris
On Sun, Jun 17, 2018 at 11:17 AM, Imants Cekusins
Well, I put in a full week in this version.
If this website is not usable, fair enough.
Let's wait for the version that suits.
_______________________________________________ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
-- Chris Allen Currently working on http://haskellbook.com
Writing software anew is the fun part, the not-fun part is the maintenance.
Agree. Writing a new version is often faster and easier. In this case the website is compact, so it is doable: why not use a new framework every time someone wants to do a full rewrite? Does the ticket rule out React? I just used the framework I knew and found fast and convenient. It is not that new, btw. If this version is not acceptable, so be it. Maybe let's add a note to the ticket: no React can be used. So we benefit from this experience in some way at least.
On 2018-06-17 19:45, Imants Cekusins wrote:
Writing software anew is the fun part, the not-fun part is the maintenance.
Agree.. Writing a new version is often faster and easier.
In this case the website is compact, so it is doable: why not use a new framework every time someone wants to do a full rewrite?
Does the ticket rule out React?
Speaking from some experience with this: I think it'd probably be simpler to do a static-ish site with e.g. Sphinx and this is not really what React is best at. (Don't get me wrong, I personally really like React.) It's definitely *possible* to do a static site using react, see e.g. https://github.com/nozzle/react-static so I don't think it's rules out a priori. (Especially since routing should be entirely static. Dynamic/async routing + statc pre-rendering rendering + React can be... painful.) However, I think it'd be best to use Sphinx since the main Cabal documentation is already done using Sphinx + ReadTheDocs and having the same build process would cause the least amount of friction. Just to add to what Chris said: I also want to say that it's great to have someone tackling this and I was perhaps a bit to blunt in my phrasing -- I apologize for that. I definitely don't want to discourage you from pursuing this further, just be sure to check what constraints you're working under. (Also not speaking in any official Cabal capacity, btw.) Regards,
The lads took it up: https://github.com/haskell/cabal/issues/4013 Please join the discussion if interested.
Hi,
On 17 June 2018 at 18:20, Christopher Allen
I don't think this is fair to the maintainers of Cabal and the Cabal website. You can't do work nobody asked for and then get upset if people are unwilling to adopt and maintain the unasked-for-code.
To be fair, Imants contacted me before starting to work on this, and I told him that using React was okay. My reasoning was that since nothing has happened on this front for several years, it's fine to use anything that gets the job done. That said, Christian's version looks more like what I had in mind when writing that ticket, so perhaps the two efforts can be combined?
(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,
participants (5)
-
Bardur Arantsson -
Christopher Allen -
Imants Cekusins -
Mikhail Glushenkov -
Thomas Tuegel