A note on the philosophy of the webkit and its documentation

[alberto]

I have been “user zero” for the webkit. After two weeks of intense interaction with @owen, Marina and I (but mostly me when it comes to handling the configuration files) are quite happy with our first result, https://research.edgeryders.eu. Still some very minor thing missing, but the site is now in use. In general, I think you guys in the tech team (@matthias, @hugi, Owen himself) were right, and this is the way to go.

During this test, an important pivot happened. Owen decided that JSON is not a good choice as the format of the configuration file, and switched to XML instead. Also, we discovered four things, that I consider important for the future development of the webkit.

1. The documentation now serves much more third-party users of the webkit than people in Edgeryders. Both the repo and the documentation website resemble those of a normal open source project. They are completely useless to Marina, or Andreja. This is not a complaint, but a recommendation that that part of the documentation is now dropped, and some effort is put into making a step-by-step manual to making a website with the webkit. I am willing to contribute to it. From Owen’s side, the first thing that needs to happen is that he produces an equivalent of the JSON example configuration file in XML. In general, the switch to XML has rendered obsolete part of the documentation.

2. The Discourse editor sucks at writing code. You get very frustrated when trying to edit code from within Discourse. When we were doing JSON, my workflow was like this:

   • Copy-paste the JSON config file into TextMate.

   • Use the collapse function of TextMate to render the JSON at the highest level, like this:

     

   • Expand one block at a time, make the edit, re-collapse, etc.

   • Copy-paste the result back into Discourse.

   Now I will need to find something similar for XML.

3. To avoid messing with the configuration files, there should be almost no text in them. Everything should be written in normal posts on Discourse, and the configuration file should point to those posts:

<Text topic="12345/1"></Text>

By the same token, everything accessible via edgeryders.eu API should be made available to the webkit. For example: whole categories; topics by tags; users, etc.

4. There is a need for themes, to standardize the Edgeryders look and feel and reduce the need for tweaking things. My next website is going to be the SF-ECON website. I am completely OK with it looking exactly like the RezNet website (of course, with its own logo, colors, and images, but same theme). If we don’t do that, we are going to spend a lot of time asking Owen to tweak things and the websites will bear no similarity to each other. Aligning the content is very fast with the webkit, so that 80% of the work is done in three hours, but without good theming the remaining 20% will take two weeks, and then, like Nadia says, we might as well build one-off Wordpress websites.

Can I ask @hugi to incorporate these suggestions in future development decisions, and in how Owen’s time is allocated?

[owen]

@alberto

From Owen’s side, the first thing that needs to happen is that he produces an equivalent of the JSON example configuration file in XML. In general, the switch to XML has rendered obsolete part of the documentation.

I would add this - there should be a clear distinction between the Open Source project and the Edgeryders version. The two are mostly the same, but there are some important differences:

1. The Edgeryders API behaves a little differently from a vanilla installation of Discourse. James built useful endpoints for fetching content - for example, for fetching topics. These endpoints should not (and are not) used in the Open Source project, as they will not work with any other Discourse installation.

2. The Edgeryders Webkit hosted at live.edgeryders.eu has a ‘multi-site’ configuration. This means one installation is the ‘backend’ for many sites - and these sites are routed through different domains or aliases (in our case defined here).

After the XML syntax, this is the second significant change made in the last few weeks.

The benefit of using a single installation means:

• Updates are deployed across all sites instantly
• We reduce overhead by only having one repository to maintain (versus many dozens, one for each site),
• We can easily use something like Netlify Analytics to get visitor stats from all the sites at once.

3. The form component, which we are still trying to integrate with the platform, requires significant customisation on the Discourse end (this was done by Matthias, James and Hugi) - and so is not standard with the open source project for now.

The final point, being this:

@alberto

The documentation now serves much more third-party users of the webkit than people in Edgeryders .

I agree and that needs to be updated… I think the XML syntax serves project managers (and myself) better than the JSON syntax, it reads like HTML and is a lot closer to writing a post on Discourse, with the use of some additional tags.

The end result is still JSON, but that part is now behind the scenes and does not require a project manager to learn. It’s far easier to write this with fewer errors:

<Content>
  <Text style="color: red">
    Hello
  </Text>
</Content>

Than this:

"blocks": {
 "content": {
   "text": "hello",
   "style": {
     "color": "red"
    }
  }
}

JSON is very picky with trailing commas, missing quotation marks or closing curly braces (and the more of them you have, the higher the risk of error). It’s an error prone format for what we are trying to do, which is easily deploy sites with minimal trouble.

So, this needs to be properly documented - probably here and will do it next.

---

Agree that themes are also very important, for the same reason as mentioned before: using a small set of CSS themes makes updating and improving the look of dozens sites a lot easier than updating one site at a time. At the moment we have two basic themes:

• The very simple default theme, used here: http://research.edgeryders.eu
• The magazine-like theme used for events, campaigns and newsletters, example here

---

Overall I’m happy with the direction the Webkit is taking and more comfortable with people using it in this form than the previous iteration…

In terms of project development, the main hurdles are (in reverse order of difficulty & time needed):

• Getting the form component to work with the platform (this has been very challenging)
• Parsing the XML tags for all the Views (slides, grids, lists, events…)
• A blog view for displaying topics
• Documentation:
  • How to use the XML tags
  • How to use a theme
  • How to configure a form
  • How to style individual elements
  • How to set up an alias and domain

[hugi]

@alberto

Can I ask @hugi to incorporate these suggestions in future development decisions, and in how Owen’s time is allocated?

I think I first need to have a session with Owen to better understand what direction the webkit is taking since got to the last milestone we set out in the original design plan. It all got into a bit of a flux with a lot of changes happening very quickly in the last month or so. I haven’t really been involved in project management for those changes, and we would need to set out a goal for what we want to achieve in the next 6 months.

@owen

I would add this - there should be a clear distinction between the Open Source project and the Edgeryders version.

I really don’t think we should be actively maintaining a vanilla version of the webkit that does not use custom webkit endpoints. I would not support us doing double work for that. After all, our webkit endpoint plugin is also open source and can be readily installed to any Discourse instance that needs it.

@owen

they will not work with any other Discourse installation.

They will work just fine if the Discourse installation has this plugin installed:

GitHub - edgeryders/discourse-webkit-components: This plugin exposes...

What is the rationale for having an “open source” version when we’ve made the plugin the webkit depends on open source?

@owen

Overall I’m happy with the direction the Webkit is taking and more comfortable with people using it in this form than the previous iteration…

I think that our highest priority now is getting us to a completely stable 1.0 version of the webkit, which is 100% documented and which will not change until a future major release. This 1.0 version needs to have all the old dead-end code stripped away too for ease of access for future development.

[owen]

@hugi

What is the rationale for having an “open source” version when we’ve made the plugin the webkit depends on open source?

owen:

If the plugin is available and open source then I see your point. It does mean some parts of the webkit will not work out of the box unless that plugin is installed however.

[hugi]

@owen

It does mean some parts of the webkit will not work out of the box unless that plugin is installed however.

I think that is fine. We are, after all, mostly building this for ourselves. If people outside of ER like it and want it to work without our plugin, they can carry the maintenance for that themselves.

[owen]

Ok - that’s probably the way to go then. I’m free tomorrow morning if you have time for a call, otherwise let me know when would suit you.

[hugi]

How about Tuesday afternoon at 15:00?

[owen]

works! Speak to you then

---

17:00 would work, or later? Otherwise I am free most of Wednesday, you just can just ping on riot when you have time.

[hugi]

Hmm, no. Better on Thursday then, perhaps at 13?

[owen]

Yep, works fine

[alberto]

Hello @hugi and @owen, I would like to ask to put two items on the agenda of your meeting today.

1. Documentation, as per this topic.
2. Can I get an update on the webkit as a funnel for registering to the platform? We are rolling out comms for the Sf-Econ first event about now, so we need to quickly decide whether to have signup via our own infrastructure or through a third party. What we need to know is when we can use a webkit website to sign up to an ER event. In fact, I thought this was working already (there are forms in Owen’s example JSON config file), but Nadia claims it is not.

Today I am starting a manual about making a website with the webkite for dummies like me.

[owen]

@alberto

1. Can I get an update on the webkit as a funnel for registering to the platform? We are rolling out comms for the Sf-Econ first event about now, so we need to quickly decide whether to have signup via our own infrastructure or through a third party. What we need to know is when we can use a webkit website to sign up to an ER event. In fact, I thought this was working already (there are forms in Owen’s example JSON config file), but Nadia claims it is not.

Will discuss in the call, but as a preliminary answer:

• There is a form component to build forms. The ongoing issue is getting this form data onto the platform. It is a work in progress, therefore I would not recommend waiting for it to launch your first event.

• What the form component can do is post the result of the form to Airtable, or any third party service with a documented API. This requires some configuration, but it works.

[alberto]

Thanks. Meanwhile, started the manual:

Webkit Usage

This is a step-by-step guide to making an Edgeryders website with the webkit. Content Understanding the webkit and why we use it Why we need the webkit and when to use it How it works: introducing configuration posts Step 1: Make the design decisions Step 2: Prepare the content Choose and structure a home for your content Make or choose high-quality content Step 3: Prepare the configuration post Make a copy of the example configuration post Edit the Config block Edit the Menu bloc…

[owen]

Thanks for getting started on this - I will add to it as we go along.

In our call today we set the following goals:

• Remaining components to be integrated and working with XML format by next week (July 2nd). The syntax of these components will follow closely how the < Text > and < Form > components work. Date: July 2nd
• Documentation finished and working in tandem with webkit - Date: July 6th.
• Form working, depending on outcome of fix - Date: July 6th

On the last point - for @alberto - I would not wait or delay an event page in the expectation of this form working. The reason is we’ve ran into a series of problems getting it to work thus far - if this last problem is easily fixed I will post a message here saying so - if not, it is best to adopt an alternative solution for your event.

There are several third party form solutions out there, but if you want the existing form integrated with a database or something like Airtable I can set that up - let me know, which way you go.

Finally, the footer for @nadia will be done today (in the next hour).

I think that covers everything - @hugi if there is anything else I missed here feel free to include it below.

[hugi]

@owen

The reason is we’ve ran into a series of problems getting it to work thus far

These problems, for the record, have something to do with the plugin @gdpelican built no longer working as expected with Discourse. @matthias is investigating.

[alberto]

@owen and @hugi, thanks for this.

I am now done with iteration 1 of Webkit Usage. There is still some information missing: I have @mentioned you to mark the points where I need you to fill it in. Once everything is in place, we can upgrade it to manual, with @matthias’s permission.

When making a website with the webkit, the main tool at the layman’s disposal is the example configuration file, or rather configuration post. I already recommended spending some care making one with example code for all the types of content supported. Now I want to add another recommendation: be generous with inline comments:

<!-- XML comment here -->

Problem with that, of course, is that an XML tag is not rendered by Discourse. We can live with it, and I already added it to the guide:

@alberto

General principle: you need to edit the configuration post in order to see all elements of it . This because Discourse hides some elements, including XML tags. So, don’t worry if the configuration post does not look right: edit it, then look at it in the edit window, and everything will be there.

That said, if anyone is aware of a better workflow, incorporate it in the guide.

[alberto]

@owen

I would not wait or delay an event page in the expectation of this form working. The reason is we’ve ran into a series of problems getting it to work thus far - if this last problem is easily fixed I will post a message here saying so - if not, it is best to adopt an alternative solution for your event.

@nadia please take note… AirTable it is.

@owen seen this? Vimeo embed does not work · Issue #55 · edgeryders/webkit_components · GitHub

[nadia]

yeah we use airtable already: https://edgeryders-start.netlify.app

[owen]

An update on the documentation and syntax -

@alberto the components are now ported over to the new syntax, an example of a site built using the new syntax can be found here: https://webkitsandbox.netlify.app

This means now:

• To display a grid of event topics I use the syntax:

<Grid template="events" tag="event_tag" />

• To display cards I use the syntax:

<Cards tag="topic_tag" />

• To display a table of topics I use the syntax:

<Table tag="topic_tag" />

• To display a set of topics in a blog view:

<Blog tag="topic_tag" />

or

<Blog category="category_id" />

There will be situations where we will want to display a custom data set, rather than topics or posts.

For example on the resilience site - we are displaying a row of profile cards. This data is stored not as posts but in a JSON format here: https://edgeryders.eu/raw/14036.json

To display an arbitrary data set, you would do this:

<Cards data="14036" />

This means “get the JSON data from topic 14036 and display it in my Cards view”.

---

I will add all this to the documentation tomorrow, and update the sandbox to the latest version of the webkit so you can try it out.

[owen]

The sandbox (live.edgeryders.eu) is now updated.

For some examples -

1. the Sci-Fi economics site has been updated to include the < blog > component
   Site: Edgeryders
   Config: SF-ECON Lab webkit XML - Raw

2. the resilient livelihoods site has been converted to the XML syntax (slider, grid, cards):
   Site: Edgeryders
   Config: Resilient Livelihoods XML - Raw

Also the Vimeo bug has been fixed.

More documentation tomorrow.

cc / @alberto @hugi