Re: Cabal website
Hi, On 17 June 2018 at 18:20, Christopher Allen wrote: > 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? ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
The lads took it up: https://github.com/haskell/cabal/issues/4013 Please join the discussion if interested. ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
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, ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
> 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. ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
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 wrote: > 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 ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
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
Re: Cabal website
(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, ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
Imants Cekusins writes: >> 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? ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
> 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 ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
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, ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
Re: Cabal website
Please use this link instead to access the demo: https://ciezbit.bitbucket.io/cabal On Sun, 17 Jun 2018 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. > ___ cabal-devel mailing list cabal-devel@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/cabal-devel
