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.

Yep, Its a ‘requirements’ doc

I’ve attached images of the .odt file (also attached) that shows the next stage of the Collabra ‘requirements’ process. I shouldn’t really call it requirements, I’m sorta being a little cheeky. 6 brief pages. A brief brief. This is all software development needs. Just images that people understand and a bit of clarifying detail in the text. As I write this I imagine many software people rolling their eyes and dismissing me as a ‘not serious’ software chap. They might be right – I’m not terribly serious – but this process turns out some pretty great software! And, importantly, little overhead makes the process fast and fun.

I made this doc out of the scribbles I posted, and then Alf Eaton and Julien Taquet and I had a 30 min remote call so we are all clear on it. Now Julien will make mocks to replace the horrible scribbles I made and we will update the docs when these are ready. Dev can start now or when the mocks are ready (mocks will take a day or two).

collabra-ctm1-1
collabra-ctm1-1-2

collabra-ctm1-13

collabra-ctm1-14

collabra-ctm1-15

collabra-ctm1-16

What you see here are 3 basic components for the Journal – we are working only with the author and reviewer roles now as the editor and admin views will be this, plus a whole lot more. We are designing these components initially as ‘thin’ as possible so we can plug them together and start getting a sense of the workflow. It just might be my current passion is surfing so I keep thinking of this process like shaping a surf board…honing it down to the right shape, layer by later. We can layer on more later (and, importantly, remove stuff) and change stuff as required. However, for now, this takes care of the submission process and next week Dan Morgan and I meet to work out the logic of the review and decision process.

And here is the .odt file: collabra-ctm1-1

Bassel Safadi

4am in San Francisco, a quiet street outside. I can’t sleep. The world seems a little mad with hyperbolic talk of fire and fury. So, now I’m awake with a few moments to think about things that don’t get out in the light of day. One of them being what happened to Bassel Safadi.

Bassel was someone I worked with once on a Book Sprint. I didn’t know him, but he is a good friend of friends of mine. I had this fleeting picture of him ‘just being one of the crew’ in the most normal sense. He wasn’t anyone I connected directly with, he was participating remotely in the event. His buddies were in Berlin with me and Bassel was ‘just there’ somewhere in the ether. Present, friendly, friend of friends.

Months later my buddies said he was imprisoned in Syria. It is at this point I paused to learn more about him. Imprisoned in Syria? What? What did he do? It was an event that stuck out angular, jutting, and severe in my otherwise comfortable world. It was then that I learned just how normal Bassel was. He was just this guy. He did some activist stuff in the area of Free Culture, the sort of stuff I work on. And yet he ended up, as I learned last week, being executed.

It just doesn’t seem fair. It’s not fair. It’s sad and stupid and above all, not normal. I feel for his buddies, his family. But most of all there is this dissonant hole in my understanding of the world. What is it doing there? I don’t understand how this can happen. I don’t think I can understand why this happened. It’s just stupid and sad.

Pondering design and reusability

At Coko, we are thinking through design and reuse. IMHO the world of software needs better design – design that is lead by creative inspiration, and not by UX best practices. It is not to say that these things are mutually exclusive, you can have both, but I like design that surprises, that doesn’t look like anything else…. that is beautiful and enticing… Design led by UX best practices tends to come out boring, evenly spaced, clean – like a cubicle. This was one of my frustrations with Booktype after I left the project. Putting design first is also one of the things I love most about Editoria.

So, what happens when you take this approach to software design (I am refraining from using the term ‘UX’ here as this doesn’t quite cut it) and yet there is a need to build for multiple systems at once. Which is the situation we are in. We are rapidly supporting a growing number of platforms built on top of PubSweet (more news of all this coming soon). To make life easier for those wishing to build on top of PubSweet, we have decided to break the pubsweet-components (eg dashboard, bookbuilder, submission screen) down into multiple ‘sub-components’ (eg. submission button, book list, submission questions etc).

But how to do that while upholding a high value for bespoke design?

I am wondering about the tension between custom design and reusable design. Where they touch is the area we are just now starting to operate in.

My initial thoughts, unravelling here as I write this! are that we do two things:

  1. when we design systems, we do only bespoke design
  2. we break the parts down that we think others may use after (1)

In a way, that means we are probably creating more work for ourselves (!) and lessening the work for others… but sometimes that is what community is about…

Still pondering…

Some articles I’m reading on the subject:

  1. https://uxdesign.cc/atomic-design-creativity-28ef74d71bc6 (many thanks to Brian Muenzenmeyer who maintains patternlab node for this recommendation)
  2. https://medium.com/ruxers/dont-mistake-common-ui-patterns-for-best-practices-4a1c8d4bef9a (thanks to Julien Taquet for the recommendation)
  3. https://www.smashingmagazine.com/2016/07/building-maintaining-atomic-design-systems-pattern-lab/
  4. https://css-tricks.com/video-screencasts/149-quick-intro-pattern-lab-node-brian-muenzenmeyer/ (video)
  5. http://atomicdesign.bradfrost.com/

Leave PDF and JATS as end-of-line formats

Over the last years, I’ve seen a few attempts and ponders about building journal submission processes around end-of-line formats – ie. PDF and JATS. I call them end-of-line formats because these formats are ‘outputs’ from other formats and processes. No one, for example, sits down and authors in JATS or PDF. Most researchers produce their work in MS Word, LaTeX and sometimes HTML and (ugh) markdown…there is also, of course, the R Markdown and similar schools that render to (for example) MS Word for submission purposes.

But it has to be said that no one authors in JATS or PDF. If they do then they are treading a long painful path when there are far simpler and painless ways to get there.

My small plea to the world is to leave these end-of-line formats where they are – at the end of the line. Keep content in flexible containers (file formats) so the works can be altered, reshaped, completely overhauled, fluidly re-flowed… whatever is needed… but don’t make the mistake of trying to either prematurely optimise document structure, or choose a file format that was not designed for authoring as your format of choice for authoring. It just doesn’t make sense. Instead, build systems that enable flexible authoring formats and layer structure on it through the process, then output to all the end of line formats you desire and QA those using the appropriate tools.

For my part, obviously, I believe that format should be HTML. I do see that it will take some time for publishers and researchers to unanimously agree with me 🙂 But I’ve seen enough people come round to the idea over the years that I believe that there is a steady rising of the HTML tide in scholarly publishing that will eventually mean all ships will rise…

coda : Seeing that my post above was not clear  (https://twitter.com/martin_eve/status/894866889343721472). I’m not arguing that we need JATS at all except that ‘to segue to the future’ we need to support it. I believe the research world would be better off without both PDF and JATS. My point is, don’t build Manuscript Submission Systems that use JATS or PDF as the primary source file format. Use HTML, and (where necessary and unfortunately) niche formats like LaTeX where you have very little chance of convincing them to use anything else.

XSweet 1.0 coming, HTML to JATS also

We (Coko) are going to work through some smaller issues on XSweet. XSweet is our XSLT scripts that convert MS Word to HTML Typescript. We need to keep filling out small gotchas but mainly we look into table conversion and some font fixes. So far though, XSweet is looking pretty sweeeeeeeeeeeeeeeeeet…..

In other news – just putting together a HTML to JATS pipeline using INK and building some INK Steps around Martin Fenner’s pandoc-JATS. We’ll experiment with this but may ultimately move to a HTML to JATS XSLT solution that doesn’t need to convert to markdown as an intermediary (as pandoc does).

What this means, is that in a week or so we could create a new recipe that chains together the following INK Steps:

  1. XSweet (MS Word to HTML conversion)
  2. HTML to JATS Typescript (a version of HTML ready for ingestion into pandoc)
  3. pandoc-JATS for HTML to JATS conversion

We don’t currently have a use case for this, but as you can see it takes MS Word through this chain and will produce JATS. We’ll test it out and see how far it gets us. In the journal world, we anticipate this would be useful to some but more interesting is to go from MS Word to HTML, ingest this into a PubSweet journal system, improve with the Wax Editor, and then output this to JATS at publish time. This way we don’t try and optimise the file too early which, IMHO, is a big mistake.

Mapping Workflows

One of the things I do a lot, is help people think through their workflows and how to optimise them. We do this for all kinds of projects – book workflows, journals, micropubs, pre-print services etc prior to developing a software with them that will help them do what they do better, enable efficiencies, while leaving the door open for continual optimisation of how they work and for possible future transformations of how they work. Drawing from my 10 or so years of facilitation experience I facilitate these processes, and Kristen, drawing from her 20+ years in publishing, is ’embedded’ in the group to be part of the conversation and foster discussion and ideas from ‘within’ the group. We make a pretty good combo.

To do this we must help people ‘think in web-based workflows’. While most journal platforms out there are accessible via the browser they are not what I would call ‘web-based’. They take no advantage of what a networked digital environment can enable. Instead, the web is used as a common way to access what are, primarily, cumbersome database ‘ledger’ systems where workflow is tracked more than it is enabled. Books are even more interesting in that book production staff primarily work directly on the file system with MS Word files. There is little proof the web exists in many publisher’s book production workflows except that they use the network to email collections of files to each other.

So, how do we get people whose primary work environment is anything but the web, to start thinking about how they might work in the web? Well, we essentially follow 3 stages:

  1. document the current workflow
  2. discuss an ‘optimum’ workflow
  3. map this workflow into browser views (we call them ‘collaborative spaces’ or, more commonly, ‘spaces’)

Each of these steps takes several hours. We allow minimum one day for the entire process detailed below. 1.5 – days would make it more comfortable.

Document the Current Workflow

It is important to start the process with all major stakeholders in the same room. Clear out a few hours, or a day, and bring along a lot of paper, post-its, pens and, preferably, some large whiteboards.

Talking through the Journal of Creative Technologies workflow (Auckland, NZ)
Talking through the Journal of Creative Technologies workflow (Auckland, NZ)

It is important to make sure all the major stakeholders are there (or representatives if some groups are large) because when you go through the current workflow you will discover that no one in the room knows the whole story. It is also often true that the organisers of the event have some fundamental assumptions about the workflow that are wrong, and that most people do not understand the knock-on effect of their actions on a co-worker’s job. All this is important to reveal through discussion, while ignoring the claim that ‘we all know what each other does’ – I haven’t ever found this to be the case so far.

This discussion should start right at the very beginning of the workflow. In the case of a Journal Manuscript Submission System, for example, the process usually starts with an author with a manuscript that they wish to submit. That is your starting point. Make sure you really do identify where it all starts as most people will tend to suggest that the early stages are known and understood and simple and consequently they may try to skip this part or deal with it superficially. But your job is to have a discussion that covers the entire workflow and get exact details of what happens, by whom, and when. So keep asking really annoying pedantic questions to get to the clarity you need. Don’t let assumptions leave anything uncovered – I have often found that items everyone assumes are understood reveal hidden, not widely understood, processes when the right, very straightforward, clarifying questions are asked. For this process, you will have to get over your fear of looking stupid! Ask as many pedantic clarifying questions as possible.

Work through the workflow step by step from start to finish. As you do this, document it clearly – a shared large space (eg whiteboard) is best. As you draw it, ask for affirmations that it is correct. Work through all the eddies and conditional forks in the workflow to their conclusion and document them. In the end, make sure you summarise this in one simple document. Theexample below is a document from the Journal of Creative Technologies workflow discussion.

cpd3-2

This is a useful process for exposing the actual (vs assumed) workflow to all players, stimulating ideas on how things could be better, and creating a ‘source of truth’ for the current workflow (people often forget details down the road).

While this part of the process is good for raising ideas on how things could be better, don’t let the group get stuck in the future weeds. Planning an optimum workflow comes next and if you let them stray too far into future thinking, they will either not finish documenting the current workflow, or they will confuse how things are now with how they want things to be. But don’t entirely kill these ‘future thinking’ moments either – let them be aired but if it looks like they are going to evolve into deep, nuanced, discussion of one part of the workflow and how it could be improved, then move discussion along. Also, make sure that all people are paying attention through this entire process. Don’t allow side conversations as these take those participants out of the wider discussion as well as distracting everyone else.

Discuss an Optimum Workflow

Next, we lead the group through an open-ended ‘pie in the sky’ discussion about possible utopian workflow futures. We start this discussion very broad – asking anyone to jump in with an idea. The discussion starts broad and we allow it to roam around a little. Often throughout this process, we are taking note of where there is agreement or ‘energy’ around a given idea or approach.

Sometimes people whiteboard ideas but most of the time it is pure discussion.

l1030128
Discussing workflow possibilities with Collabra Pyschology Jourmal

After a while, perhaps 30 mins, maybe more than an hour, we start bringing back some of the ideas into the discussion that we know the group was interested in and ask them to expand it together. Sometimes we drop in small hints that a particular idea might be a good one but is technically unfeasible – this starts to give the group a sense of what is possible, or what might be technically achievable in the short, medium, or long term. It’s important not to squash ideas as soon as they emerge but to ‘sober them up’ if they get too fantastical. A little bit of realism doesn’t hurt at this stage but, more importantly, you want to get the ideas flowing. Nothing is nailed down or committed to at this point, it’s just exploration and discussion.

Mapping

Now we get to mapping these ideas onto a web-based platform. The group is going to engage in systems design without knowing they are doing so. We do this by first explaining a little about the web – some of the things that are possible. We might show some examples of sophisticated web-based editors like Wax, or in-browser pagination using Vivliostyle. Perhaps we might look at Trello/wekan or kanban examples of workflow management. We might look at Stencil.a or any number of examples of interesting platforms and approaches the web can offer.

We also talk about the efficiences of the web and how that is enabled – mostly this comes down to unpacking why a single-sourced content environment is so powerful, why ‘everyone working on the same object’ is important, how collaboration and concurrency can change the way we do things. As well as preparing them for the idea of designing a new system that is native to the web, we are introducing some new ideas that might reshape how they think about how they work. Why, for example, do we email MS Word files around when we can simply all see the same document, at the same time, in the browser?…these ideas will mean different things to different groups and how they play with them depends on how ready they are to explore new possibilities, combined with how much of their ‘old ways’ they are prepared to let go, plus how much they understand about the web. So it is important to let this conversation go at its own pace across whatever topics the group feels they need to explore. It is important that the discussion evolves of its own accord from the ideas introduced. We ‘shape’ the conversation, point it in a certain direction and signpost with certain interesting examples, rather than provide a soliloquy or monologue about how we would like things to be done. This is important, because unless the group internalises these ideas, they won’t end up exploring them when it comes to design time.

Next, we give a little rundown about ‘thinking in collaborative spaces’. Basically what we are trying to do is to take some of the ideas that emerged in the ‘optimal workflow’ discussion and start prompting them to think how this might be realised ‘inside the browser’. Most commonly we can do this by talking about very concrete things like browser windows, which everyone knows, and asking ‘how could this part of the workflow happen in a browser window?’ For example, in a journal system, we might ask ‘how might submission happen for an author in a browser window’? As a starter example, we could discuss this and draw a box on a whiteboard and draw some basic ‘UI’ elements in that box. This makes everything very very concrete. You are reducing systems design to something they understand without them realising that they are about to start designing a system.

The next step can take several directions, but the most common is that we split the group into smaller groups. 4 or 5 to a group is usually a good number. We then give them large sheets of paper and a bunch of thick pens, and send them to acoustically separated spaces to draw up proposals for ‘several spaces’ that would represent the workflow in the browser. The time we give them depends on the time at hand. You want more than 15 mins, but 45 is probably too long. Sometimes we might also ask them just to focus one one part of the workflow, usually the first part (however you design this is up to you).

l1030400
Erich van Rijn (UCPress) pitching some ideas to the group while Dan Morgan (Collabra) documents, and Paul Shannon (eLife), and Yannis Barlas (Coko) listen.

It is very important when you send them away to do this that you ask them to draw the interfaces. One big page of paper, for example, per ‘space’ (browser window). If you don’t do this some groups, especially those used to writing requirements docs, will write lists. The problem with that is that these lists don’t tend to be scoped or connected very well. They just turn into a list with as many items relevant to (for example) ‘submission’ as you can imagine. Better is if they draw the spaces as if it was a browser window, putting in UI elements with basic drawing.

img_9414
Oliver Buchtala (Substance.io) holding up his group’s proposal at Erudit, Montreal.

No one has to be an artist, it just needs to be a rough proposal of what that space would enable, and one most people will understand if they were just to look at it.

l1030396
John Chodacki (CDL) puts some finishing touches on a proposal he designed together with Andrew Smeall (Hindawi), and Jure Triglav (Coko).

We circle around and make sure everyone is getting on with the task and in good time. At the end, we bring everyone back into the room and ask them to present their proposals to the rest of the group.

l1030423
Lia Schiff (CDL) presenting a proposal to the rest of the group.

We give them a short amount of time to make the presentations. Perhaps 10 mins, more if the scope of the workflow is larger.

l1030464

What you will be surprised at, I can guarantee it, is that all the proposals are *great* AND they will all be very similar. We have done this many times and the results of each group are rarely very far apart. When they are far apart, it’s usually because a group has locked onto one idea or another as a starting point and designed everything around that. These ideas usually have something very worthwhile that can be combined with the other proposals to improve them.

As each group finishes presenting a space or group of spaces we ask the group for questions or comments. We don’t let this go too deep into the weeds as time is tight at this point, but some discussion is always useful.

img_9420
Another proposal at the Erudit workshop.

Then at the end, you discuss these approaches and agree on a common approach. We call this an ‘architecture’ which it is to an extent. It is the bird’s-eye view of how their new workflow will fit snugly into a browser based workflow. The following being an early ‘architecture’ or high-level systems view of a journal platform for Collabra.

scrap015_a2

Handily each of these new spaces can then be built as a PubSweet component! The following is the architecture showing the components we need to design and build – this diagram was the result from early sessions with the staff from UCP I facilitated to produce the Editoria monograph production platform.

components-ucp

This process is a very specific description of the first part of the Cabbage Tree Method. The second part of the Cabbage Tree Method involves facilitating the design of each of these components.