Surfing and Stuff

I’m taking a holiday in Hawaii to surf and do nadda for a week. I hired a 9ft Walden Magic from Mikes Maui Beach House. Nice folks. Wind is up but I had a good day yesterday on some small waves.

In the meantime, Coko had a big announcement. Announced at COASP (Conference for Open Access Scholarly Publishers) by eLifes Mark Patterson. You can find the complete announcement here:

In essence, eLife is building on top of PubSweet to build their new manuscript submission system. They will possibly re-use parts of the PubSweet components built for Collabra. That’s the beauty of the PubSweet ecosystem – you can reuse what you want, and build only the new stuff (significantly reducing the burden).

We are already collaborating with eLife and have been for some 4 weeks to refactor parts of PubSweet according to some excellent recommendations made by eLife and their dev partners YLD. They are all great people to work with.

Stay tuned, more interesting news to come!

Going where your people are

Recently, I have been involved in some discussions around what tools to choose for open communities. This came up with regard to the Open Source Alliance for Open Scholarship (links to the new website coming soon!).

One argument that always comes up with these kinds of discussions, and I have been involved in many, is that we should use platform X because ‘thats where the people are’. Because open source has lost in the platform game (but its not too late) this argument almost always points to a closed source platform eg. github, twitter, slack etc

‘Going where the people are’ feels intuitively like a good idea. You want your project to succeed, go where the people are. Hard to argue against that. But argue against that we must, and I’ve started to think a little about how to counter this position better because sometimes, when people get stuck on this argument, there is no budging them.

One thing I have experienced recently that has fed a counter argument is the growing community around Coko. We use Mattermost and Gitlab as our primary web spaces for community and collaboration. What I notice with our gitlab, for example, is that when you open it up in the browser it looks like Coko. It looks like a home for a variety of connected and interesting projects that all revolve around Coko’s mission to reshape publishing. It is my hope that this will grow to be even more true over time. If that proves to be the case, then this gitlab instance will be a home (possibly one of many) for a certain approach and certain kind of thinking about how to change publishing. And that there is incredibly valuable because it speaks to the need for your community tools to surface and reflect your communities activities and values.

Coko GitLab

That’s not so easy to do in github. Go to a github org space and it looks like every other github org space. It looks dull. It reflects the identity of github and not of your community. This doesn’t just come down to theming, but it comes down to more subtle nuances such as with gitlab (or similar open source solution), the space is committed only to the things your community is doing. Things that are not connected are not a click away. From a community members point of view its a space dedicated to them. In this day I believe this is increasingly more unusual, important, and appreciated.

Consequently, I use the argument that developing community identity is more important than ‘going where the people are’. Don’t create a space ‘where the people are’, create a space where your people can go.

Working on xpub

Much is going on in the Coko world at the moment and a lot of news coming out soon about various collaborations. Much of the attention has been around xpub, the journal system we have been working on built on top of PubSweet.

PubSweet is, of course, a component based system so you can ‘roll your own’ journal or book platform from existing components. We are making a lot of components for both Editoria and xpub and publishing them for reuse with an open source (MIT) license.

Some of the components we are generating for xpub are coming out of the work we are doing with Collabra, the UCP Psychology Journal. Today the Managing Editor, Dan Morgan, and I met for another session working out the logic of the components and how they fit together.


We started by working through the flow from the perspectives of each of the major stakeholders – Managing Editor, Senior Editor, Handling Editor, Author, Reviewer. We worked out what they each needed to see on the dashboard and then went through their workflow and what they needed from each component.

List of what each actor sees on their dashboard
List of what each actor sees on their dashboard
Mapping out the flow across components.
Mapping out the flow across components.
Sketches of components
Sketches of components

We then took each of these small mappings and transferred them to larger pieces of paper. Drawing the interfaces in basic form.

Drawing out the components in detail
Drawing out the components in detail

Each of the diagrams are detailed below.






We had already worked out this structure. Today was about running through the logic from each actor’s point of view. Good news is, the logic held up and validated the architecture. Good news! So, what you see in these pics is more or less what we will build. It is a thin horizontal slice that covers the complete lifecycle of a manuscript going through the Collabra process. We’ll build it and test it, and then layer on additional functionality.

Next I’ll recreate these in digital graphics and add a page of bullet points for explanation. We will then meet with the Coko team and talk it through and start building! It’s a good way to design systems, way better than endless months gathering pages and pages of product requirements. It’s a lightweight and fun process. Software is a conversation after all!

Atoms, Molecules, Patterns

I’ve just had a rather interesting dive into the world of components. At Coko we are breaking down the PubSweet components, essentially browser views, into smaller ‘sub-components’. So we looked at the language, best practices, and tools in this arena.

The outcomes are pretty simple but also interesting. We decided to use React-Styleguidist for the management of these sub-components.

But the discussion around what should constitute a component/pattern is in itself interesting. There is some interesting theory around it, probably the most compelling document I found was the Atomic Design article/thesis by Brad Frost. It is a compelling language / framework for understanding and discussing the creation and use of reusable components.

There are two questions that seem fundamental to a sub-components (patterns) approach:

  1. at what level do you describe something as a (singular) ‘component’?
  2. when should something become a component?

The first is very much the topic of the Atomic Design book linked to above. Brad Frost uses the metaphor of chemistry to describe the basic component types, the first being an atom. An atom is the most basic element that you will find on a web interface (his language is very much built around web interfaces and HTML elements).

atoms include basic HTML elements like form labels, inputs, buttons, and others that can’t be broken down any further without ceasing to be functional.

So, a button could be a component, and if so it would be the most basic type – an atom. That makes intuitive sense to me and its an interesting way to talk about things. We all know atoms are the most basic form of matter, so using the term to describe the most fundamental form of UI element is an easy translation. It is also a nice language to adopt because in the world of atomic theory atoms exist in isolation but they also exist in clusters and there is a language for that too. Two or more atoms that exist together form a molecule.

molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule.

That also translates pretty easily. There are other layers after this. The ‘next layer up’ (so to speak) Brad Frost calls an ‘organism’:

Organisms are relatively complex UI components composed of groups of molecules and/or atoms and/or other organisms. These organisms form distinct sections of an interface.

I can almost buy the ‘organism’ terminology but not quite. I would prefer something like ‘compound’. This makes more intuitive sense to me. As the Free Dictionary states:

Consisting of two or more substances, ingredients, elements, or parts.

So, I would prefer – Atoms, Molecules, and Compounds. I’m not going to nit pick Brad Frosts essays, it’s a brilliant piece of work. I guess I’m just pondering about the consistency and intuitiveness of his chosen lexicon. Atoms and molecules work for me, compound feels easier than organism…anyways, I got into the weeds,

The point is, each of these is a component but this gives us the language to talk about different types of components – which is very important.

Incidentally, Brad Frost defines two more layers – Templates, and Pages. I’m still pondering these. I’m, for now, mostly interested in atoms, molecules and organisms/compounds.

So, this is nice. I felt this framework made immediate sense when I first came across the idea (recommended by Paul Shannon from eLife) and, further, I felt the stress disappear caused by the struggle of talking about ‘different types of components’ without being able to name them.

Which leads me to the second question I asked above – when does something become a component. In other words, when do you spend the time to make the component a component, whether it would be an atom, molecule or compound component. For this, I am very grateful for an insightful and brief chat I had with Brian Muenzenmeyer who maintains the node version of PatternLab (Brad Frost is also part of the PatternLab team).

Brian made this very nice point:

I recall a friend explaining to me to start worrying about making something a pattern at all only after you use it three times. First time, it’s a one off. second time, you have a convenient template to copy/paste from. third time, it becomes a maintainability issue

It is a very salient point as it also points out, implicitly, that patterns are emergent and it doesn’t pay to be over zealous when breaking something down into an individual component/pattern. I think that is smart. Having said that, we possibly occupy a smaller % of software spectrum where re-use is more fundamental to our work than, say, someone building a company website. This is because we are building for reuse. Coko produces systems so that others can inherent or build their own publishing platforms. So, to support the later (build your own publishing platform) I think it is important for us to build reusable components from the get go to make it easier for developers to roll their own platform ie. we should create reusable components whenever possible as a matter of course.

Lastly, while PatternLab has Brad Frost’s logic built into it, there is no need to use PatternLab to make atoms, molecules and compound ‘stores’ for components. These can be established in the naming and categorization by convention in other tools eg React-Stylguidist (our choice of tool). This is not to say PatternLab is a bad tool, it is a great tool, but if you subscribe to Brad Frost’s ideas, or some version of them, you don’t need PattenLab to achieve this. You can choose the tool you want based on other requirements.

Anyways…that is my thinking on it so far. Pretty interesting topic. I am grateful for the language and clarity that Brad Frost provides and a few sage words on when to think about making something into a component from Brian Muenzenmeyer. Still pondering all this. It’s a very interesting area.

Onto Journals…

We (at Coko) have been working with Collabra Psychology to develop a Manuscript Submission System with them. The cool thing is, we can re-use a lot of work that we put into Editoria since we built PubSweet with the notion of highly reusable components (on the frontend and backend)…

I find it so satisfying to see our ideas and hard work put into building systems with the ‘right level of abstraction’ paying off. We are pretty much putting together a cluster of tech that can be re-assembled to meet a huge variety of publishing workflows very quickly…

The platform is called ‘xpub’ for now and it’s looking pretty good. We were able to assemble a basic dashboard, submission page, and editor plus link it up to INK for MS Word -> HTML conversion in a matter of days. All still in early days but looking great.

Login page for our first Journal platform.
Login page for our first Journal platform.

You knew the day was coming … 🙂

Coko and Communities

Kristen Ratan (co-Founder of Coko) and I have been pondering ‘the next phase’ of Coko. We have an organisation in place, with great people, and we have developed products (Editoria, and more coming soon) and frameworks (INK and PubSweet). Also, of course, we have developed the Cabbage Tree Method for facilitating ‘users’ (use-case specialists) to design their own products.

So…next up… community. It seems to me it is an interesting next phase which will require a lot of thinking about. The complexity comes from the fact that we have multiple primary stakeholders at play. A rough breakdown (note, each category is a complex ecosystem of diverse roles – all of which we still have to think through):

  1. PubSweet backend – this is a ‘headless CMS’ built for publishing workflows… however, it is a technical software whose primary community would be developers that commit to its continued development. Additionally, I would argue, its use-case is a whole lot broader than capital P Publishing… any organisation that wants to develop workflows for producing content (which is pretty much every organisation that exists) could benefit from this software. Publishers are just a tiny subset.
  2. INK – the web service for (primarily) managing file conversion pipelines. This is also a technical ‘backend’ whose primary community would be developers. INK’s use-case is also broader than ‘just’ publishers.
  3. INK Steps – INK processes files through steps which are small plugins. These can do anything from file conversion, to validation, content parsing etc…. the primary community for this is possibly more tightly connected to publishing requirements, but the builders of steps are more likely to be those involved on the production side of the workflow ie. file conversion experts, content miners etc
  4. XSweet – a very specific content conversion pipeline for producing HTML from docx. Primary community would be file conversion experts.
  5. Editoria – the monograph production platform. Primary community – Publishers but also interesting to any org that produces books.
  6. Journals – we are on our way to producing a Journal platform. The primary community for this is also publishing organisations…
  7. Ecosystem – we are building out an ecosystem of projects. So as much as possible we need to consider how we interact with and build community/collaboration with other open source/open access (etc) projects.

It is a complex stack..our job is to work out all parts of this stack, understand what they look like, and think through why they would want to be involved in a community, and how…

Coko’s Efforts getting Out ‘n About

It seems the Coko meme is getting out there. Just these last few weeks we have seen the following: – we put some money into assisting ‘, including flying the founder Nokome over to San Francisco and introducing him to funders. The result is that Nokome just landed a very nice grant from the Sloan Foundation. We don’t lay any claim to Nokome’s great work, but it’s good to see that our help was instrumental in helping this great project along the way.

HTML Typescript – Recently (last week) Wendell Piez, who we work with for Docx to HTML file conversion, presented at the well known JATSCon about his work with Coko. The preliminary proceedings are available online for Wendell’s talk and I hear the video will be available soon too.

Texture – if one slot at JATSCon wasn’t enough… Texture was also presented. It is an online JATS editor produced by the Substance Consortium which we co-founded. Proceedings here.

Penguicon, Carnegie Mellon – I recently presented Coko at these two events and upcoming we will be presenting Coko and various projects at SSP, AUP, Open Source Lisbon, Wikicite, OSEHRA, Open Source Albania and more!

March for Science – Coko CoFounder Kristen Ratan was lead organiser for the San Francisco March for Science. I couldn’t be there (was in the desert) but it apparently was a wonderful event.

Open Source Alliance for Open Science – we have 28 open source projects for open science coming to join in a day working out how to work together. Starts tomorrow in Portland!

Lots happening 🙂