Use a static site generator for the CoTech website and host on GitHub Pages

@harryrobbins do you have any information on the features you commissioned? We have the jobs board on discourse - is it designed to replace that? I'd be happy to see how hard it would be to model individuals in Jekyll.

I believe it will be easier for people in all co-ops to contribute design expertise to the proposed solution as the barrier to entry is a knowledge of static HTML and CSS (rather than php / wordpress / docker etc). I think the concern about hosting goes away with this proposal as we could use Github Pages. If not hosting static content should be simpler than wordpress.

James addressed an idea about making it (somewhat) easier for non-developers to contribute. And we'd be more than happy to contribute to the learning group on Git/Github suggested by @asimong - I think the CoTech website would be a great place for people to dip their toes in the water of collaborating using git.

How does Jekyll work for reciprocal links (e.g. I click on a service and see the co-ops that provide it, and I click on the co-ops and I see the services they provide?)

Is it fair to say that updating the content (e.g. adding a new co-op, adding a new service) will become harder while editing the theme (changing the CSS, etc.) will become easier?

How does Jekyll work for reciprocal links (e.g. I click on a service and see the co-ops that provide it, and I click on the co-ops and I see the services they provide?)

We have this working already. You only need to list the services against a coop and that will mean those services will be listed on the coop page AND all coops offering that service will be listed on the service page, i.e. you only need to edit the data in one place. The latter is achieved using this code.

Is it fair to say that updating the content (e.g. adding a new co-op, adding a new service) will become harder while editing the theme (changing the CSS, etc.) will become easier?

That's true to a first approximation, but I think that content editing is only very slightly harder, while development, deployment and hosting are substantially easier.

It's also much easier to collaborate on content changes with the Jekyll/GitHub approach - as I've mentioned previously I found the Wiki + Wordpress workflow very confusing and error-prone.

I think people are attached to the things they are familiar with :)

I am not sure which way my bias goes, I default to making Jekyll sites if I can, but I also have been contributing to the docker-compose setup for cotech wordpress site [1]. I am probably slightly biased towards the wordpress site because it is the currently running one, and having worked on the docker setup for it.

In terms of more objective measures, I checked the equivalent template in the Jekyll [2] and Wordpress [3] sites. To my eyes those are pretty much identical. In both cases you are mostly editing plain HTML, with a sprinkling of code (liquid, or php) to fetch the data.

For project setup complexity, whilst Jekyll sites just require ruby (and bundler), people that are not already in the ruby world often have issues, especially with gems that need to be compiled natively (in this case the natively compiled gems are ffi and nokogiri [4]). If it was switched over I would advocate still having a docker version available for more predictable development environment. So far we have been able to get non-dev users to get the cotech wordpress site up and running locally with one command (docker-compose up) - and should be working across linux/mac/windows.

For ease of use for editing content I would tend to defer to whoever might be actually doing the content editing. I think this is not me. I occasionally meet non-dev people that are happy to use github ui for markdown content editing, but not many, although given this is co tech perhaps that ratio is higher. Personally, I prefer the github model for all the reasons stated by @jamesmead / @chrisroos, but again i don't think I will be doing much content editing.

The final aspect I don't know much about - the future plans for the website, if it is intended to have more dynamic features (signup, forms, email sending, search, etc) then Jekyll is obviously not a good fit for that need (unless embedded js solutions are good enough). Or perhaps the vision is for a static brochure site, and have a separate site with dynamic features?

/endessay

[1] https://github.com/cotech/website/pull/41

[2] https://github.com/cotech/statically-generated-website/blob/7cd609d6743509cd1925a264de44ccf7d9bbc657/_layouts/service.html#L38-L46

[3] https://github.com/cotech/website/blob/9dc2d44820d04039c8991b34688ad770d5d4dce4/web/app/themes/coop-tech-oowp-theme/views/service.php#L37-L41

[4] https://github.com/cotech/statically-generated-website/blob/2416ec49404e44463b859d8da614600b20c12d41/Gemfile.lock

Static HTML is ideal from a hosting point of view, however, although people have struggled with development of the WordPress site, nobody has had a problem with adding Co-ops, Services or Technologies -- I fear that this is what we would loose with a switch to a static site generator -- the ability for just about anyone from any tech co-op with a login to, very easily, add content to the site.

I agree with this. When new co-ops sign up, we ask them to add their details to the site. Considering that not everyone in the network has the same tech skills, my concern is that the proposed version of the site will make it inaccessible, and it will either fall back to the same people each time, or not get done.

I agree. Plus, if at some time we wanted the site to handle transactions between members (not necessarily financial) that would mean moving away from static.

What about the idea I suggested yesterday, that we select the technology that works best overall, with the best resonance with our co-operative values, and with the most overlap with other work we may want to do, and help each other learn it? Is Wordpress a good solution to handling transactions? I wouldn't have imagined so...

No, but why change twice?

Sorry, @shaunfensom -- no what? I lost context. I don't suggest changing web technology more times than needed. The only disadvantages I can see for learning twice are time and motivation. All I'm suggesting is that we don't base our choice of technology mainly on what people currently know, as we can learn, and learning can be useful in other ways.

@asimong ha! Loomio not good at holding thread context. You said: “Is Wordpress a good solution to handling transactions? I wouldn't have imagined so…” so I said “No, but why change twice?”

You ( @asimong ) said: “Is Wordpress a good solution to handling transactions? I wouldn't have imagined so…” so I ( @shaunfensom ) said “No, but why change twice?”

I still agree :) If we might want some kinds of transactions in the future -- perhaps in the sense of people identifying with appropriate use cases as adding real value -- then if we can move to a technology that supports such transactions, great, other things being equal (which they never are, of course, but anyway...)

I'm in favour of sticking with the current set-up until such time as a compelling argument is made to change (and by that I'm saying that i don't consider the arguments made thus far to be compelling). The biggest single issue surely is what the plans are for the future, as others have hinted at.

Right now this feels like a solution looking for a problem. In my world about 1000x more people know how to fumble around in Wordpress than even know what Github is.

There's some great feedback here and we appreciate it, thank you!

To address Graham's point: there's certainly a concrete problem we're trying to solve here which is that we had some spare time to contribute to CoTech and make it easier for people to find out more about our network (by moving some wiki content to the site and adding some new information pages) and the current system prevented us from doing that easily. Developing, deploying and modifying the current system is currently very difficult.

It sounds as if there's some broad consensus that static pages are easier to host and deploy (hosting static HTML is commoditised to such an extent that Github for example offer the facility for free). This gives us less support, security updates and maintenance to worry about/donate time to/pay for.

It seems that the principle objection is the ease of adding new content to the site. I note that some of the current information is out-of-date - so I'd need some more evidence to convince myself that we've already cracked that problem.

What can we do to convince people to adopt this proposal? I think we've learnt that using version control software (and github in particular) isn't familiar to some members - it's such an important part of our daily work that we took that for granted.

We've made some suggestions of how people could edit the content using the github user interface - would someone who is not familiar with that approach be willing to test that in the prototype with and give some concrete feedback?

We would be happy to give a short video demonstration if it would help.

It seems that the principle objection is the ease of adding new content to the site

The other key point was which features the site should have in the future, and how they would be implemented in each of the solutions.

Yes - I think there's a meta-discussion here about approaches to building software. The idea of anticipating future requirements now and adopting a solution today that can cope with those anticipated requirements versus using the simplest possible solution to today's problems and iterating on it as requirements change and we have more information. I'd say Go Free Range favour the latter approach in general. I don't want to take this discussion off on too much of a tangent so I haven't addressed that issue in detail.

From a (purely) comms standpoint, seems to be a 'function before form' thing going on. It's our (general) public-facing website. So, assuming we want to 'say' more than we already do (do we?) ... isn't it better to decide what that is/will be ,then decide how best to do it?

Ignore if I've the wrong end of the stick...

@chrislowis I agree with your approach to development. Right now though (with a site already running) the simplest possible solution is to do nothing at all :)

I've put together a sequence of screenshots demonstrating:

1. A GitHub user creating a pull request to add a new cooperative using only the GitHub user interface
2. The pull request being merged
3. The changes automatically appearing on the website

I purposefully made life more difficult for myself by using a user who is not a member of the cotech GitHub organisation and by adding two files (content and logo) in one go.

I can see how this could be a bit daunting for those not familiar with GitHub and it is clearly slightly more complicated than using the Wordpress admin interface. However, there are lots of advantages to working like this and whether or not this proposal is accepted, we (Go Free Range) would love to help members of CoTech learn more about how to use GitHub and/or git to collaborate on stuff.

Do let us know if you have any questions.

Hi Team!

First off thanks GoFreeRange for putting your spare time towards developing the CoTech site. Effort. An it's great to see all this chatter going on about the site, and which ever way we decide to take it i think it's great that everyone is thinking about the future of CoTech and the site.

Also "would someone who is not familiar with that approach be willing to test that in the prototype with and give some concrete feedback?" sounded like an after lunch thing so i thought i'd give it ago.

Heads up. I'm not a dev. I am use to light touch editing content in WP when i need to.

Did the 10 min tutorial you suggested. Seemed alright.

Managed, i think, to get a version of the site and gave myself the task of adding a service to outlandish.

Looking at the site in the folder layout at first is a bit scary, but seemed to make sense so i headed for services, looked at the file structure for business analysis, then created a new one BIG-DATA. tried to keep it the same formatting as not to break it.

Then thought i best upload the picture, so headed to the directory for the images and dropped in a png.

Then i wanted to add it to Outlandish services and shoved it below the other service.

One thing that stood out for me is that i'm still not sure whether it's done. As i couldn't preview the changes i was making, or maybe i missed it. I mean i could see that the changes were there but i couldn't see the output.

I ain't logged into the current WP version but i imagine in WP i can create a new service, add an image, and then select all the coops that it applies to from the one page, and then preview the changes across the service page, coops that have that service page. Which i think is v handy and would be something that i might get asked to do.

So… feedback I think WP is good for the basic user putting up content use case. Git felt a little bit and back and forth which might just be because its my first go, and i still don't know how to see if what i did worked and thing that theme stuff should be accessible via GIT. then i can't go in and break it, which i think i did :)

Anyway the above is probably not concrete feedback and it's just based on the short task i thought i could do in WP an try it out in GIT so it would be good if anyone has 30 mins to give it a go.

In terms of the proposal changing it over to this model I think it would limit others in adding content to the site rather than wordpress which is more familiar to a larger number of people usede to editing content.

An i say this as a none tech but i wonder if the scheduled time proposed could be used on new features instead of a re-make of what we've got? If tasks lived https://trello.com/b/XbjLBKNE/cotech we can maybe shape them together and then figure out priorities schedule them in and see which member coops can take on what.

Sorry if a board already exists that i'm not aware of.

T'ra

@mattcrow:

Many thanks for having a go at making some changes. There was a small error in the first pull request which I fixed and merged. The second pull request was fine and I merged it unchanged. Your changes are live on our version of the site. I think all this could be made easier with some simple instructions and file templates.

One thing that stood out for me is that i'm still not sure whether it's done. As i couldn't preview the changes i was making, or maybe i missed it. I mean i could see that the changes were there but i couldn't see the output.

You can see a preview of Markdown documents, but you're right that you can't preview how all the changes will look on the website, i.e. with styles applied, etc. To see the changes on the website the pull requests have to be merged.

If there is an error re-generating the site after a merge then the site is not updated, so there's not really any risk of seriously breaking anything. If having merged you see a problem on the site, it's easy enough to make more changes to fix them.

If you were a member of the cotech GitHub organisation, you would be able to merge your own pull requests or even make changes directly to the master branch which would make the whole process a lot simpler.

Personally I don't see the lack of "preview" functionality as a problem, but I know others may see this differently.

Thanks again for your feedback. :smiley:

Perhaps it's useful to see this as a both an opportunity for a little bit more of cotech to become less dependant on Outlandish; and as a significant input of time and energy from another coop to the cause.

If Go Free Range are happy to shoulder the burden of pushing the site forwards for a while, and are offering to help anyone who wants to add content or learn more about publishing content to a static site, then I say GO FOR IT!

I just wanted to say a quick thanks to everyone for all the feedback and to reiterate that we really appreciate all the work that people have put in to the existing Wordpress site.

It'd be great if a few more people could look at and ideally try to make changes to the Jekyll version of the site to give us some more feedback, maybe by following this step-by-step guide. We'll be around in CoTech Slack if you have any questions.

Once we've got a bit more feedback, we'll mull over what everyone has said and come up with a suggested way forward.

Is it worth going back to the core user need here?

The frustration seems to be twofold:
1) I can't update content on the site.
2) I can't update the look and feel and the actual code of the site.

With regard to 1) I am finding it difficult to imagine why people are having the problem here. If you have an account on the site is it that difficult to update things? For developers in this conversation it seems that you don't have a problem with using WordPress it is just not your preferred technology as a developer. For others it seems sure that WordPress is more familiar and convenient. Changes are reflected instantaneously on the site.

With regard to 2) imagining you have used the new Docker Compose setup to boot the site, added functionality or changed the look and feel, put in a merge request and then had it checked and merged. The problem is the delay between this and deployment, which I understand is a manual process by @chriscroome. If it were not and a merge was after a spell live on the site would people be satisfied? I would be happy to facilitate with @chriscroome any additional devops work needed to make the "merge to master, code goes out" a reality.

I also concur with @nicksellen on the potential cold experience of using Ruby for newbies. Native extensions can always cause headaches - especially Nokogiri, but this is the same in all languages to some extent. In my experience when building a site of any level of sophistication beyond content display is you end up writing custom Ruby code. Which is fine. But something in the mix.

So a further: do people envision adding to this site in a way that exceeds the boundaries of flat content display? I don't know about @harryrobbins use case he refers to above about a jobs board and so on, but presumably this sort of thing, especially with the searching, filtering and other functionality will mean some degree of bespoke code writing with a flat site. In which case, we are back to where we are as I outlined above.

Hello,

I am late in the party (blame me for turning notifications off by default) and if there is a +1 to add on moving to a static website I would add one.

WordPress is a decent solution — it worked so far but issues were rather on the Ops side of things. It requires a different environment to test, data state is bound to a DB and changes submissions can't be discussed as we tend to do on the community website or on loomio.

It's the big value we get with static generators, plus the ability to map data to different views (a coop can be an HTML page or part of a JSON output — it connects well with https://community.coops.tech/t/mapping-co-ops-and-their-relationships/54/48). It's explicit, there is no magic, no runtime error.

I am happy to pair up with Go Free Range folks to prototype an isofunctional website in Jekyll. I'm around in July and August 👍

We (Go Free Range) chatted about this over lunch today. It feels as if a lot of people are uncomfortable with the idea of not having something similar to the Wordpress admin interface for editing content and it's not obvious that many people have run into the difficulties that we have with making changes to the site. So while we would be happy to offer to take the lead on a statically-generated version of the site as @olizilla suggested, for the moment we're going to park the idea; we can always come back to it later. Thanks everyone for listening to what we had to say! Cheers, James.

For completeness, NetlifyCMS (open-source) provides an admin UI for editing content as a React app mounted in the Jekyll app. Siteleaf (commercial with free plan) provides a similar UI hosted on their own domain, but pushes changes to your GitHub repo. A bunch of similar projects/services are listed here.

We've got a bunch of clients on active sites backed by a db, that ultimately, I have to babysit.

The sites that are happily getting updated without any support are the ones that we run on jekyll, but hide that from the client behind a tool we built that's similar to https://www.netlifycms.org/ that shows a fancy wordpress style editor to the users, and turns their content changes into commits to the repo. I've never had to explain git to them.

We make updates to the templates to change the UI, and the editors make changes to the content. All the changes are tracked so we can roll back either sort of change to any previous version, with zero bespoke code to do it. There's no active processes running other than a httpd/nginx frontend, which in most cases is serving thousands of other sites and are often someone else's problem, the sites are super snappy to load and feel a pleasure to access for the user and are easy to reason about, work on, test and improve from the dev side too.

As I'm debilitatingly hot right now and my laptop is trying to kill me, I'd add, perhaps foolishly, that re-building the site once, automagically, when some edits the content rather than tickling the db and assembling the page every single time someone looks at it is easier on the CPU and ultimately the environment.

Perhaps a fairer comparison here would include https://www.netlifycms.org/ as the editor ui.

This is more of a fundamental tech ideology point for me than a direct discussion of anything that will ultimately benefit the mega-cotech-zord, so I take it on board that there are better places I could be directing my energy, but pretty much my entire working life has been absorbed by tech projects that are more complicated than they need to be, so please forgive the zeal on this.

I'd like to voice my support of @olizilla specifically for the value of simplicity in software, and interfaces. Unnecessary complexity excludes -- unnecessarily.

I have noticed in other places (not here) that people promoting complexity stand to benefit, by being part of the elite who has invested in being able to understand and work with that complexity. I really don't think that anyone in CoTech would remotely want to do that, but maybe some people may be more attuned to the value of simplicity than others?

From an amateur-only development point of view, I'd be happy to participate in a conversation along the lines of "where is the optimum simplicity to be found here?"

I think people might fear the complexity of WordPress a little too much - there are tens of thousands of plugins and themes, many or most of which are written by amateur coders (which has its own disadvantages). We've hosted lots of sites that have happily looked after themselves for the seven years we've been going and the clients have been happy.

I think there is a duty now for the people who advocated sticking with WordPress (myself included) to make it easy for people to update the site (thanks to @chriscroome for making the https://dev.coops.tech/ version and setting up auto-pulling from github already).

Can I suggest that we turn our attentions to what we actually want from the site. The current one was knocked up pretty quickly without much thought or research. I'm sure that between us we have lots of good ideas for features or improvements.

Outlandish would quite like to add a 'skills finder' (previously inaccurately referred to as 'jobs board'). Essentially it would list all the individual members of CoTech and list their skills and experience. We think it would be useful for finding co-ops to collaborate with, winning work by showing our diverse expertise, making it clearer who we are and what we do, etc.

Obviously before adding anything to the site we'd want to check with everyone that they agreed it was a good idea. We're currently doing some wireframes of what it might look like and @bradleyreeder and @jenspencer are going to be getting in contact with everyone to find out if they like the idea, what would make it better, etc.

Once we have a clearer direction it might be more obvious which technology we should use. For example, I've already got a feature that I'd really like on the jobs board that would be very difficult to make with WordPress (and Jekyll, I think).

I've started a thread on Discourse for discussing new features, etc.

Can I suggest that we turn our attentions to what we actually want from the site.

It was never our intention in this thread/proposal to make a technical change for its own sake - rather by simplifying the technology and bringing the content and software into a single, versioned repository in GitHub we hoped to make collaboration easier and more transparent. We're delighted to get involved in that irrespective of the tech choice.

Outlandish would quite like to add a 'skills finder' ... Obviously before adding anything to the site we'd want to check with everyone that they agreed it was a good idea.

I hope you don't mind - I've added this issue in GitHub to track the discussion and any code changes to support this feature. It seems like a good place to get feedback and allow people to contribute to its development. @bradleyreeder and @jenspencer - do let me know if you haven't used GitHub before and need someone to give you a quick overview.

I think @kayleighwalsh mentioned an idea about visualising collaborations within the network, showing how interconnected the coops and the services they provide are. (e.g. Outlandish collaboration with The Small Axe on School Cuts)

@ievapadagaite - ah yes! It's a really interesting idea. I notice there's an issue for the modelling aspect of this. @chriscroome was investigating it. Thinking about the visualisation would be amazing too - there's a discussion on the community site about some of that.

I recently started using https://getgrav.org/ - and it offers an intriguing combination of the benefits of wordpress and jekyll.

I'm not suggesting anyone remakes the website using it, just sharing my enthusiasm!

For my main use cases (small, mostly static multi language content sites) it fits nicely between wordpress (too complicated) and jekyll (too simple) and so replaces them both.

• it's a "flat file" cms, so everything is in human editable files (yaml/twig/scss) hence can be managed using git, pull requests, feature branches
• it comes with an admin ui that lets you drag and drop images, install plugins, themes, etc... (you can run it locally, then manage any changes as git commits)
• if you use the gantry plugin you get a fancy theme editor (drag n drop layouts, nice font selection / color / file / image pickers, etc...)
• multi language support is built in and works well
• can easily add custom admin ui (e.g. adding faq items)
• it's not a static site generator, so can do some dynamic stuff (send emails from forms, resize images on automatically, randomize a list of members on a team page, search)

@nicksellen sounds cool. The new CoTech co-work/events space needs a website so maybe this (or a static generator) would be a good use case?

Also @chrislowis @ievapadagaite @kayleighwalsh yep - you can now add your collaborations here: https://www.coops.tech/wp/wp-admin/edit.php?post_type=collaboration

The data about the collaborations can then be extracted and visualised by all the super keen coders out there. Those coders don't necessarily know what the visualisation needs to look like in order to be useful/interesting so any thoughts you have would be useful.

@nicksellen sounds cool. The new CoTech co-work/events space needs a website so maybe this (or a static generator) would be a good use case?

@nicksellen / @harryrobbins - We (Go Free Range) have agreed to create the CoTech co-work/events space website and are planning to use a static site generator (almost certainly Jekyll + GitHub Pages).

Awesome @chrisroos - thanks to Go Free Range. Any design-type co-ops thought about the future of the main site?

This discussion might be better on the Discourse forum?

One issue with GitHub (and GitLab) pages is that you have to manually upload a HTTPS cert and although this can be automated with free Let's Encrypt certs the script still needs to be run once every three months.

So if you would like a static hosting account with automatic Let's Encrypt certs and the ability to upload using SFTP / SSHFS then we could provide this (and wouldn't charge CoTech for it) and we could also add a crontab if need be to do a git pull as we have for the WordPress sites, this could use a sub-domain, eg space.coops.tech or another domain.

One issue with GitHub (and GitLab) pages is that you have to manually upload a HTTPS cert and although this can be automated with free Let's Encrypt certs the script still needs to be run once every three months.

Good point, @chriscroome. I hadn't even been thinking about SSL when thinking about the Outlandish co-working space (now named Space4) website.

So if you would like a static hosting account with automatic Let's Encrypt certs and the ability to upload using SFTP / SSHFS then we could provide this (and wouldn't charge CoTech for it) and we could also add a crontab if need be to do a git pull as we have for the WordPress sites, this could use a sub-domain, eg space.coops.tech or another domain.

Thanks for the offer, @chriscroome. We'll bear this in mind when we're getting something up and running.