This manual covers the use of Kotahi. While it provides Kotahi documentation, its scope is broader - to help you rethink and design workflows.

This manual aims to:

• explain Kotahi's capabilities

• provide tools to evaluate, design, and evolve workflows.

• guide Kotahi configuration to encapsulate your way of working

• provide assistance to all Kotahi users

If you first wish to understand how Kotahi works, we have included descriptions of all the interfaces and high-level concepts in the chapters Kotahi Explained, Settings, CMS, and Production.

If you wish to get quick help on specific topics, go to the How To Guides section.

However, the workflow chapters provide important conceptual foundations. The Tips on Setting Up Your Workflow section especially bridges workflow design and Kotahi capabilities.

Consider reading the workflow chapters to reflect on processes, even if you are not changing your workflow now. Technology decisions should follow, not drive, workflow needs. Use this manual to take a step back and rethink how work gets done.

For years, academic publishing has relied on legacy systems that hinder efficiency and scholarly communication. Complex interfaces frustrate users. Rigid, one-size-fits-all submission systems cannot accommodate diverse content, workflows, or journal requirements. Email-driven communications cause delays. Production remains siloed externally without automation. Monolithic architectures hamper scalability.

At Coko, we believe it’s time to move forward. Driven by a passion for improving research sharing, we developed Kotahi to tackle these systemic challenges. Initially funded through our surplus, and later with help from partners like eLife who share our vision, Kotahi is designed to modernise workflows for traditional and emerging publishing models.

This documentation represents a key milestone for the project - the Kotahi 2.0 manual.

The platform tackles key challenges - making standards like JATS attainable without technical staff. It provides enormous flexibility to customise workflows as needed. Sophisticated multitenancy enables the hosting of multiple journals, preprint review, and preprint servers within a single install. Automated PDF production enables consistent, high-quality typesetting at scale. The microservices architecture allows independent scaling and updating of components.

Now, you will have the information in your hands on how to leverage the powerful features of Kotahi.

Scholarly publishing is evolving rapidly, and Kotahi is designed to improve how research is currently shared while anticipating future needs. By improving existing workflows and anticipating emerging models, Kotahi represents the innovative future of research communication.

What is Kotahi?

Kotahi is an open source publishing platform designed to modernise workflows for journals, preprint servers, preprint review communities, and other models. It provides a flexible system to support diverse publishing needs.

What are the key features of Kotahi?

Some key features include configurable workflows, multitenancy, automated JATS and PDF production, drag-and-drop form building, support for any metadata schema, tailored peer review, real-time communications, task management, and more.

What publishing models can Kotahi support?

Kotahi can support traditional journals, preprint servers, publish-review-curate models, overlay journals, micropublications, and more. Its flexibility enables many emerging publishing paradigms.

How does Kotahi support preprint review?

Kotahi enables the import of preprints, AI-powered recommendations, custom review forms, collaborative annotation, grouped reviews, and flexible publishing of reviews or curated collections.

What review models does Kotahi offer?

Kotahi supports single-blind, double-blind, open, collaborative, community self-review, multiple iterative rounds, and combinations of these models.

How does the Kotahi form builder work?

The intuitive drag-and-drop form builder allows creation of submission, reviewer, and decision forms without coding. Forms can be designed from templates or customised.

How does Kotahi produce JATS XML?

Kotahi provides a simple production editor for users to visually tag document sections. These are automatically mapped to JATS XML elements on export.

How does Kotahi create PDFs?

Kotahi leverages Paged.js to automatically paginate manuscripts into print-perfect PDFs with professional typesetting and formatting.

How does task management work in Kotahi?

Advanced but customisable task management allows configuring workflows at a per-group or per-manuscript level with reminders, actions, and invites.

What multitenancy capabilities does Kotahi offer?

Kotahi enables hosting multiple isolated journals, preprint servers, or review groups within one installation while retaining custom workflows for each.

How is Kotahi designed to be customisable?

Kotahi is highly configurable through its settings and also extensible via plugins, APIs, and microservices. Coko offers customisation services.

What benefits does Kotahi's architecture provide?

The microservices architecture enables independent scaling and updating of components along with overall flexibility and resilience.

How difficult is it to install Kotahi?

Kotahi utilises Docker and microservices to simplify deployment. While sysadmin skills help, the goal is accessible self-service installation. There are third-party hosting and publishing services vendors that can also help you with Kotahi hosting.

Is Kotahi open source?

Yes, Kotahi is 100% open source software published under the MIT license. The code is freely available on GitLab.

How do I get technical support for Kotahi?

Join the Coko Mattermost for community support at https://mattermost.coko.foundation

Who created Kotahi?

Kotahi was created by Coko, a non-profit developing open source publishing infrastructure. Learn more at https://coko.foundation

The following is a brief summary of some key Kotahi 2.0 features.

Flexible workflow

Kotahi is more than just a journal platform - it is a comprehensive scholarly publishing platform. Kotahi offers a range of customisable workflows that go beyond traditional journals, allowing teams to collaborate and process research objects according to their specific requirements.

Kotahi advances publishing in three key ways:

1. Supporting legacy workflows - Kotahi can operate traditional journals, while offering extensive configuration options to optimise workflows over time.

2. Enabling new workflows - Kotahi is built for emerging models such as publish-review-curate, and more. Its flexibility supports micropublications, curated knowledge compendiums, and other innovations.

3. Allowing experimentation - With multi-tenancy support, Kotahi enables setting up multiple teams/journals to test new workflows at no added cost. Teams can run legacy systems while experimenting with new models.

Overall, Kotahi provides adaptable infrastructure to encapsulate diverse publishing models and ways of working, both current and emerging. Its configurability aims to move scholarly publishing forward.

Multitenancy supporting diverse use cases

Managing multiple scholarly publishing groups like journals, preprint servers, or preprint review communities has traditionally required running separate software for each one. This quickly becomes cumbersome and difficult to scale.

Kotahi resolves this issue by providing native multitenancy support for many use cases within a single integrated system. This allows a single Kotahi installation to host any number of journals, preprint servers, or preprint review communities in the one installation.

Each group functions independently with its own:

• isolated data and privacy

• customisable submission workflows

• unique look and feel

• publish endpoint

The key benefits of Kotahi’s multitenant approach include:

• reduced software overhead since only a single instance needs to be maintained

• workflows tailored for each group without conflicts

• easy scalability when adding new groups

• streamlined cross-group analytics and reporting

• the ability to experiment with new publishing processes within the one system

This architecture substantially reduces the complexity and costs of operating diverse portfolios of journals, preprint servers, and review communities. As publishers scale up their groups, new ones can be easily onboarded while retaining custom workflows.

By supporting this kind of sophisticated multitenancy natively, Kotahi establishes a new standard for flexibly managing any number of publishing groups, with any number of different workflows and use cases, on a single streamlined platform.

A modern, powerful CMS

Kotahi incorporates a modern content management system (CMS) based on static site generation rather than a traditional database-request-driven CMS. This approach provides significant advantages in speed, security, and scalability.

Compared to a traditional CMS which can become sluggish and vulnerable at scale, Kotahi’s CMS remains lightning fast and rock solid regardless of traffic or content volume. This innovative architecture ensures publishers can manage content efficiently while providing users with a reliably fast experience. Full text articles are published at a push of a button. The CMS can handle the demands of complex scholarly publishing requirements both now and in the future.

Automated JATS production

The Journal Article Tag Suite (JATS) XML standard has become ubiquitous in scholarly publishing, allowing content to be structured, exchanged, and preserved in a consistent machine-readable format. However, many publishers have found the JATS format complex, costly and cumbersome to implement, and have said that the specialised skills and effort required by the format drive up costs, hamper efficiency, and create barriers to adopting this critical publishing standard.

Kotahi aims to change this status quo by integrating JATS production seamlessly into the publishing workflow.

At its core, Kotahi sees a document as a constellation of content, primarily in the form of the manuscript text itself, and associated metadata. Both categories of information are transparent to Kotahi as the system ingests manuscripts at submission time and converts them to an internal file format. Customisable submission forms designed in Kotahi gather comprehensive metadata up front.

The internal production editor then provides an intuitive way to prepare content for JATS export without needing direct XML skills. Users simply visually highlight and tag content sections, and these selections are automatically mapped to the appropriate JATS document elements. On demand, Kotahi converts the prepared manuscript and metadata into validation-checked JATS XML that complies with all specifications. This standards-compliant JATS file can also be regenerated as needed throughout the editorial workflow. Kotahi also has an evolving set of tools for the management and validation of citations.

By integrating JATS production into the publishing pipeline in this tailored yet automated manner, Kotahi makes adopting JATS accessible to mainstream publishers. The platform’s innovative production tools lower the barrier to entry while facilitating standards compliance at scale, reducing overhead costs, and accelerating publishing turnarounds.

Automated production of PDF

One of Kotahi’s standout features is the ability to automatically typeset and generate print-ready PDFs with just a click. This is powered by the integration of Paged.js (also built by Coko), an open-source library for paginating HTML content into high-quality PDF documents.

As manuscripts in Kotahi are edited and stored as HTML, Paged.js can fragment the content into pages, inject sophisticated print styling, and paginate a preview within the browser. When ready, the print-perfect PDF can be saved out (or batch processed) - no manual typesetting is required.

This browser-based PDF generation approach also enables automated workflows. Kotahi can thus produce press-ready PDFs at scale in a fraction of the time and at little or no cost. The result is a system that can take manuscripts from writing to publication-quality typesetting with unparalleled efficiency. Hands-off, consistent, and aesthetically pleasing PDFs become accessible to publishers of all sizes through Kotahi’s simple automation.

Drag-and-drop submission form creation

Another of Kotahi’s standout features is the ability to create submission forms using an intuitive drag-and-drop interface. This removes the need for any coding knowledge or technical expertise. Users can easily add, remove or rearrange form fields as needed.

Whether working from pre-made templates or designing fully customised forms, the entire process is quick and user-friendly. For authors, filling out submissions becomes simpler, with reduced chance of errors. This results in more complete information being captured upfront, benefitting downstream teams.

Compared to traditional form creation methods which are often complex and time-consuming, Kotahi’s drag and drop approach simplifies submission management for publishers and authors alike.

Support for any metadata schema

The submission process for journals and other preprints requires capturing metadata - information about the manuscript itself. However, traditional systems often force standardised schemas that lack flexibility.

Kotahi provides versatility by supporting submission and publication using any metadata schema, including custom schemas or niche standards. This adaptability lets publishers capture optimal metadata for their domain and needs.

Kotahi provides possibilities for action through a number of methods, but largely through its drag-and-drop form builder where any metadata tags can be attached to submission fields. It also supports capture of complex nested data via custom form elements - this enables capture of detailed author information, for example.

For authors, submitting manuscripts is simpler when providing metadata in appropriate domain-specific schemas. For publishers, post-submission overheads are reduced by capturing comprehensive, flexible metadata up front.

This metadata can then be configured to be pushed through to the appropriate publishing end points.

By empowering customised metadata capture, Kotahi ensures journals and publishers get the specific information they need while authors provide it painlessly. This metadata versatility represents a key advantage of Kotahi’s submission system.

Tailored peer review process

The peer review process is a crucial element of scholarly publishing. However, traditional systems often enforce a rigid, one-size-fits-all approach.

In contrast, Kotahi provides flexibility to tailor the review process to each journal or review community’s specific needs. Different models including open, blind, or double-blind reviews can be configured. Reviewers can collaborate on shared reviews while also providing individual feedback if desired.

Kotahi enables customising the level of author participation as well. Review workflows can allow authors to respond to reviewer comments via threaded discussions if needed. Annotations (comments) made directly onto manuscripts are also supported.

Kotahi aims to facilitate constructive conversations between authors and reviewers to improve manuscripts. As peer review evolves towards more collaborative exchange, Kotahi provides built-in tools ready to enable this emerging review model.

By supporting tailored review workflows, Kotahi offers the capacity to design the peer review model best suited to the publication needs. This flexibility and customisability result in higher quality, more meaningful reviews.

Real-time communication tools

Effective communication between authors, editors, and reviewers during the submission and peer review process is key. However, email is not always the ideal medium for these interactions.

Kotahi instead incorporates real-time communication features including live chat and video chat to facilitate conversations as needed. All communications become visible within the platform, eliminating email clutter.

Users can quickly get answers, resolve issues, and streamline collaboration all within Kotahi’s interface. Smooth end-to-end discussions from submissions to publication become possible.

Customisable task management

To streamline worklow, Kotahi incorporates advanced but customisable task management capabilities. Project boards provide an overview of tasks and workflows across the publishing lifecycle.

Granular controls allow configuring task management at a per-journal or even per-manuscript level. Automated reminders, actions and invitations are configurable within the task manager itself.

This results in workflows that are tailored to each manuscript’s unique needs.

Versioning

Kotahi supports versioning of submissions to track revision history across review and editing cycles.

Each new submission round creates a new version of both the manuscript content and submission metadata. This allows tracking a submission from initial draft to final published form.

Versioning provides a record of all changes while ensuring users only interact with the current definitive version.

This version control system is crucial for collaborative workflows where manuscripts go through many stakeholder hands. Kotahi maintains submission integrity and clarity through automated version tracking.

AI-powered preprint recommendations

Kotahi also has some advanced features to support preprint review. For example, Kotahi enables AI-powered preprint recommendations that assist curators in identifying relevant manuscripts for review.

For preprint servers like bioRxiv, new submissions in specified subjects are automatically imported. Curators can then select preprints of interest for review.

Based on these selections, Kotahi leverages various APIs and AI services to recommend related preprints that may also warrant review. Checks help ensure only recent submissions from a preconfigured time period, and from approved preprint servers, are suggested.

This tailored AI-matching allows curators to rapidly pinpoint the most pertinent preprints to evaluate and disseminate within their field or community. This enhances the efficiency of preprint screening while making evident hidden gems curators may have otherwise missed.

By combining Kotahi’s infrastructure with the power of AI-powered recommendations, the platform aims to accelerate preprint discovery and review - getting impactful research into the right hands faster.

Configurable, customisable, and extensible

Kotahi is designed to be highly configurable, customisable, and extensible to meet diverse publishing needs.

The system already allows individual configuration of workflows, review models, metadata schemas, CMS and publish endpoints, task management, and more per group. This enables tailored setups without software and the need for developer assistance.

Further customisation can be achieved through integrations, plugins, addition of new microservices or new functionality and the Kotahi team is ready to support organisations wanting to customise, extend, or configure the system to their needs. Whether it’s tailored workflows or custom enhancements, Kotahi provides the versatility to meet publishing requirements and Coko is here to support you.

Microservice architecture

Kotahi is built using a modular microservice architecture. In contrast to monolithic platforms, components are designed as independent services that work together.

This provides benefits including:

• scalability - services can be individually scaled as per demand

• flexibility - issues with one service don’t propagate across the system.

• resiliency: Issues with one service don’t propagate across the system.

As publishing needs grow and evolve, Kotahi’s microservices make scaling, upgrading, and maintenance simpler and more cost-effective.

Smooth installation and deployment

Although designed for flexibility, Kotahi offers straightforward installation and deployment. It employs a Docker-based architecture with modular microservices that reduce complexity.

While basic sysadmin skills are recommended, Kotahi aims to streamline the initial setup process. Once deployed, the system can scale groups and content without requiring deep technical knowledge.

Ongoing enhancements continue to simplify installation and configuration further. The goal is an accessible system where publishers can easily leverage Kotahi’s capabilities with minimal engineering overhead.

With its lightweight microservices and consolidated design, Kotahi enables publishing teams to get started swiftly and focus on content creation rather than technical hurdles.

100% open source

Kotahi is published under open source licenses, with all source code freely available. This enables publishers the full freedom to use, modify, and distribute the software to meet their needs.

As open source software, Kotahi benefits from community contributions and transparency. Anyone can inspect the codebase, propose improvements, report issues, or create customisations.

This open development model also helps drive rapid innovation as the platform evolves via a kind of ‘public peer review’. Organisations can collaborate to extend Kotahi rather than reinventing the wheel.

By being 100% open source, Kotahi represents a publishing platform unencumbered by proprietary restrictions. This liberates publishers to fully utilise Kotahi as a strategic asset customised for their requirements.

Kotahi provides versatile tools extending far beyond traditional journal workflows. Kotahi enables end-to-end management of journal article submission through publication, with customisable reviewer selection, multi-round review, author proofing, and output generation.

However, Kotahi is not limited to mimicking journals. It can be used as a preprint server, house preprint review processes, provide overlay features, and innovative community curate and peer review models.

Additionally, Kotahi facilitates new output types like micropublications and interactive data papers. Authors can publish bite-sized findings enriched with multimedia and data visualisations.

While purpose-built for scholarly communication, Kotahi adapts for uses beyond academic research. Customisable stages, reviewers, and decisions enable grant proposal evaluation or student work submission and review.

In essence, Kotahi provides open architecture to empower new communication paradigms across research and education. It brings flexible workflows and formats beyond the limitations of traditional journals.

Kotahi is highly configurable and can publish a wide variety of research outputs. Here are some of the main options:

Types of content

• Evaluations - Review content and decision summaries from the peer review process. This could include full verbatim reviews or edited excerpts.

• Data - Datasets, metadata, code, multimedia, and other supplementary files.

• Manuscripts - Preprints, journal articles, conference papers, micropublications, and other scholarly documents.

Publishing destinations

• Internal CMS - Kotahi has a built-in content management system (CMS) to display content. The CMS is customisable to fit your needs.

• External endpoints - Kotahi can publish to any external endpoint or system provided it can receive the data. This includes institutional repositories, preprint servers, journals, archives, social media, and more.

• Multiple targets - Content can be published to the internal CMS, external endpoints, or both simultaneously.

Configuration Options

Kotahi allows flexible configuration of publishing in various ways:

• publish any combination of evaluations, data, and manuscripts or none at all

• publish to single or multiple endpoints

• customise metadata, identifiers, licenses, formatting, layouts, and more

In summary, Kotahi enables publishing virtually any scholarly content anywhere through a highly configurable system.

Kotahi supports a wide range of peer review models that can be customised for your journal's needs. Options include:

• single-blind review - reviewers know the author's identity but their identity is hidden from the author

• double-blind review - the identities of both the author and reviewers are hidden from each other

• open review - the identities of the authors and reviewers are known to each other

• collaborative review - reviewers can discuss the submission together and collaborate on a review. This can be moderated or unmoderated.

• community self-review - the review process allows the community to self-select as reviewers without editor assignments. Often used for preprint reviews.

• multiple rounds - as many iterative rounds of review as needed with the same or new reviewers each round (typical for Journals)

• rolling submissions - authors can update submissions during an active review round if enabled (this has proven useful for some preprint review use cases)

In summary, Kotahi is highly configurable to support single-blind, double-blind, open, collaborative, community self-review, and combinations of these models. The system allows multiple iterative review rounds with flexible reviewer selection and updated submissions.

Kotahi supports several pre-baked workflows for a quick start without having to understand all the congfiguration possibilities beforehand.

The four pre-configured workflows (it is possible to add more with the assistance of a developer) include:

Journal publishing workflow

Supports an end-to-end traditional journal publishing workflow; author submits, editors triage, with support for multiple peer review cycles and publishing to Crossref and other endpoints including export to PDF and JATS. 

Publish, Review, Curate

Supports an end-to-end publish, review and curate (PRC) workflow; imports manuscripts from a preprint server, editor triage, customisable submission, review and evaluation forms and publishing endpoints. 

Preprint review

Use a single submission form to capture and publish metadata, peer reviews and/or evaluation reports. The right choice if the team is not required to manage an end-to-end workflow, and a lightweight solution that’s easy to use. 

Preprint review 2

Import manuscripts from a preprint server. Use a single submission form to capture and publish metadata, peer reviews and/or evaluation reports to an endpoint. This configuration makes use of a Manuscripts table, providing an overview of all objects in the system, with specific features to support the triage process. 

The right choice if the team is not required to manage an end-to-end workflow, and what’s needed is a lightweight solution that’s easy to use. 

Kotahi has a number of screens or pages connected together that allow for the amazing versatility of workflows. From a very high level, the interconnected ‘spaces’ or pages look like the following.

Each of these is convered in detail in this documentation. Here is a brief overview:

1. Dashboard - the starting page for most users where new submissions are created and associated research objects accessed.

2. Submission page - where metadata and files for new submissions are provided.

3. Manuscripts page - a configurable listing of all research objects in the system. Access controls can be customised based on workflow needs.

4. Control page - where review cycles, tasks, and decisions are coordinated. Access can be limited or open depending on hierarchy preferences.

5. Review page - the interface for reviewers to provide feedback on submissions.

6. Production Page - enables output of publication-ready files like PDFs and author proofing.

7. Settings - configuration options for the platform.

8. CMS - controls for customising public-facing pages along with published content endpoints.

To get started with Kotahi, focus on learning the Dashboard, Manuscripts Page, and Control Page.

These spaces enable most core workflows and provide a general understanding of Kotahi's capabilities. The modular architecture allows flexible arrangement of screens to meet a wide variety of use cases.

The Dashboard shows you the research objects you are assigned to.

Here you can see all the research objects for each role within the group. The above example displays 3 tabs:

1. My Submissions - the list of research objects submitted or created within the group

2. To Review - the list of research objects to review

3. Manuscripts I’m an editor of - the list of research objects for which you are an editor / curator

Within each of those tabs there is a list which is different according to the tab selected:

My Submissions

In the My Submissions tab (the tab displayed by default) the following columns are shown:

1. Manuscript ID - the unique identifier (created automatically by Kotahi) for each research object

2. Title - the title of the research object

3. Status - the status of the research object (see below)

4. Created - the date of creation/submission

5. Updated - the date when something was last changed

To Review

In the To Review tab the following columns are shown:

1. Manuscript ID - the unique identifier (created automatically by Kotahi) for each research object

2. Title - the title of the research object

3. Your Status - the status of the invitation.

Manuscripts I’m an editor of

In the Manuscripts I’m an editor of tab the following columns are shown:

1. Manuscript ID - the unique identifier (created automatically by Kotahi) for each research object

2. Title - the title of the research object

3. Status - the status of the research object (see below)

4. Reviewer Status - a graphical status display of the reviewer process

5. Updated - the date when something was last changed

6. Updated - the date when something was last changed

7. Actions - a link to the control panel and team pages for the research object

8. Indicator - an icon indicates an overdue task

Sorting

All columns within each of the Dashboard tabs are sortable. To sort click on the name of the column you wish to sort by, to reverse sort click the same column name again.

Filter

To filter the Status column, click the dropdown and select the state to be viewed e.g ‘Unsubmitted’. Sorting can be applied on a filtered view.

The Manuscripts page is generally only available to Kotahi Group Manager and Editor roles.

The Manuscripts page is entirely configurable, so the actual columns you may see in your version might be quite different to the example above (taken from a journal configuration of Kotahi).

The above image shows a very different Manuscripts page configured for a preprint review workflow.

The Manuscripts page displays all research objects in the system.

All columns are sortable, one click sorts a column in ascending order (0→9, a→z), a second click sorts in descending order (9→0, z→a).

Automated ingestion of submissions

Kotahi can be configured to import manuscripts automatically from the Settings→Configuration→Manuscripts page. If the Manuscripts page displays a refresh button as below, this is for the automated batch ingestion of submissions. Generally, this is used for the ingestion of preprints from various sources but the functionality could be used for batch ingestion of other types of material.

In most use cases, this button is used for ingesting preprints from various sources using its AI-powered engine. If the ‘Refresh’ button is available, pressing it will trigger this automated process. The system can also be configured to ingest preprints on a regular schedule without needing the button to be pressed. This automated ingestion helps keep your preprint collection up-to-date efficiently.

Discussions

There is a live discussion (chat) available for all members who have access to the Manuscripts page.

The chat also two very powerful features - rich text (including math) and @mentions. In addition, video chat is available. Clicking on the camera icon displayed will open a video chat room.

Rich Text

Clicking on the small icon to the left of the ‘Your message here...’ input field will display a rich text editor toolbar:

This enables rich text to be created or edited if the content is cut and pasted into the chat input area. Math is also supported using the $$ syntax.

@Mentions

Typing ‘@’ into the chat input area will display a pop-up of users that can access the chat.

Selecting the name of the person you wish to notify will send them an email notification.

Hovering your mouse over a message reveals an ellipses menu which contains actions to edit/delete a post. You can also mute (press) email notification communication per channel from the ellipses menu at the top of the chat viewport.

Every research object has its own Control page. This is used by the team to manage the review and publishing process.

There are 5 tabs:

1. Team - the team (editors and reviewers) is managed here

2. Decision - this is where the management of the decision/evaluation takes place

3. Manuscript text - the full text (if applicable) of the research object

4. Metadata - the full list of metadata associated with the research object

5. Task and notifications - where tasks are managed for this specific research object and where manual notifications can be actioned

Additionally, at the top of the page is the version dropdown. This dropdown persists across all tab views.

The version dropdown displays the name of the research object AND the version or ‘round’ you are currently in. Research objects can be reviewed in multiple rounds, and in each round Kotahi creates a new ‘version’ (of all data) of the submission. The latest version is always displayed when you visit the control page, but you can browse earlier versions from the dropdown.

In addition, there are two chat rooms to the right of the page which are also persistent across all tabs.

The Discussion with Author is for the team to use to chat with the author (if applicable) that submitted the research object.

The Editorial discussion is for the team to use to chat with each other about the research object. Reviewers also have access to this channel. A video link is also available for a group chat if required;

Team tab

The team tab enables assigning of the editorial team and invite reviewers.

To assign Editors, simply choose the person from each of the dropdown menus for Senior Editor, Handling Editor, and an additional Editor.

In the case of preprint review communities or other workflows, these roles are best considered as as team members, each with the same level of privileges for managing the process around the research object.

To invite reviewers, simply select a user from the dropdown menu (listing all users in Kotahi). Note: typing the first letters of the preferred reviewer will trigger the autocomplete function. If the user does not exist in the system, you can invite someone via email by clicking the ‘New user’ option:

Here you can enter the name and the email of the reviewer you wish to invite. They will also receive an email invitation and if they click accept from the email, their account will be created and the review will be associated with their new account.

Review status

It is possible to see the status of all reviews at a glance:

Invited - existing/new users have been assigned as a reviewer. This can be done manually or by sending a ‘Reviewer invitation’ email notification.

Accepted - the reviewer has accepted the review from the ‘Accept’ action displayed on the Dashboard→To Review page or embedded within the email notification.

In progress - the reviewers have accessed the Review page.

Completed - the reviewers have submitted a review. A review submission is uneditable.

In the Reviewer Status window (shown above) you will notice ‘Version 1’ in the top right corner. This is the version or ‘round’ number (see above).

As reviewers are invited and progress through the workflow, the reviewer icons will automatically progress through the flow from left to right.

Clicking on a reviewer card will display a pop-up with further information:

If the review is completed, this pop-up will display the actual review. Additional controls allow the editor to ‘Share’ the review - this enables submitted reviews to be visible to other reviewers who have submitted a review and have the ‘Shared’ enabled. ‘Hide review’ will hide the review from the Author when a Decision is submitted, and ‘Hide reviewer name’ will anonymise the review on the Review page.

Clicking ‘See Declined’ at the bottom of this area will display all declined invitations. Reviewers who decline an invitation to review are directed to a landing page where feedback on the decision can be captured, and the user can also choose to ‘Opt out of further requests’ to participate in a peer review.

Decision tab

The Decision tab displays all the information and controls necessary to determine the outcome for the current review round.

As with many things in Kotahi, the Decision form is entirely configurable (see section on Decision form), so the form you see is displayed on the Decision tab.

Completed Reviews are displayed at the top of the tab for ease of reference when compiling evaluation/decision summaries. Clicking on ‘Show’ for each completed review will display the actual review.

Below the decision form are two buttons - Submit and Publish.

The ‘Submit’ button sends the decision and associated information to the submitting author. If the decision was ‘accept’ then the ‘Publish’ button will change to an active state. Clicking on ‘Publish’ will publish the research object. Publishing itself is entirely configurable so what happens at this moment will depend on how your Kotahi group is configured.

Manuscript text tab

The manuscript text tab displays the entire manuscript (if submitted as a docx) in the Kotahi scholarly word processor.

Comments can be made in the editor. For a full rundown of how the editor works, please see the section on the Kotahi Scholarly Word Processor.

Metadata tab

All metadata added to the research object will be displayed here.

What is displayed on this screen depends entirely on how the metadata submission form has been configured. For example, Submission form fields that are hidden from the Author are accessible to the editorial team from this tab.

Tasks and notifications tab

This page displays the tasks and notification controls for the research object.

Notifications

The Notifications controls allow you to send email notifications to registered users or to new users. To send a notification to a registered user simply select their name and the notification from the dropdowns and press ‘Notify’.

To send a notification to a new user (unregistered user) simply click on the ‘New User’ box, enter their email address and name, choose the notification and press ‘Notify’.

When the notification has been successfully sent, a check appears next to ‘Notify’ on the button, and you will also the action event recorded in the Editorial discussion chat.

Tasks

The Tasks section displays all tasks for the research object.

The initial task list for the research object will be inherited from the task list set up in
Settings →Tasks (see that section). It is also possible to add/delete/alter the inherited list to suit the needs of the specific research object.

Tasks can be created, edited, deleted, modified, started, and reordered from this interface.

Adding tasks is done via the ‘+’ button at the bottom of the task list.

Starting a task can be actioned by clicking on the ‘Start’ button. Starting a task will change the status of the task to ‘In progress’. Associated email notifications will only be sent on the due date if the task is ‘In progress’.

Pausing a task can be done by selecting the ‘Pause’ status in the dropdown menu. This will also suppress email notifications that are queued to be sent.

You can mark a task as complete by clicking on the left circular ‘Done’ checkbox or selecting the status of done from the dropdown menu.

Adding a task title and adding an assignee can all be done via the input fields provided. The assignee dropdown displays a list of roles and the full searchable list of users in the system for selection.

Duration can only be edited by opening the task for editing.

Deletion or editing of the tasks can be managed through the icon displayed between the task title and the assignee.

Deletion will ask you for a confirmation before completing.

When editing a task the overlay for that task will appear.

Duration can be changed from the ‘Due date’ item on the left. When clicked it will display a date picker.

Clicking ‘Add Notification Recipient’ will display an interface for adding new recipients of notifications. You can add as many recipients as you like. These notifications are triggered according to the de date set.

The input fields require a chosen recipient from the Recipient dropdown list. You can also add a recipient that is not registered in Kotahi by choosing ‘Unregistered user’ from the dropdown. This selection will display additional fields for the email address and name of the recipient.

You then set when the notification is sent out. The notification can be sent at a time of your choosing (including Send Now) relative to the due date of the task. The Send notification fields allow you to choose a time before or after the due date by the number of days you require.

A record of email notifications sent manually or automatically are captured in a dropdown list, in descending order based on the date and time sent. System emails are sent by ‘Kotahi’ and notifications sent manually use the username as sender id e.g. ‘Ryan Dix’.

If an email notification cannot be sent due to a configuration error, then a warning icon will be displayed on the ‘Send Now’ button.

The basic Kotahi roles are as follows:

Admin

Admin is a global role with access to all groups. An Admin has system administration permissions and access to the Dashboard and Settings pages. Admin permissions support the configuring of groups (Configuration manager, Forms, Task templates, Email templates and CMS settings) and managing Users globally. Admins don't have permission for various editing tasks unless they are assigned as Group Managers or Editors.

Group Manager

A Group Manager has managerial permissions within a group. They can access the Dashboard, Manuscripts, Reports and Settings pages. A Group Manager can assign editors. They can also perform editorial tasks themselves even without being assigned as an editor. They also can manage users within their group.

A Group Manager is the only role that has access to the Manuscripts page and has oversight of all the manuscripts within their group. This role can facilitate a curation role in support of manuscript triage, for example.

Currently, this role also has access to the Production editor from the Manuscripts page.

Admin users who are also assigned as Group Managers can delete any Discussion message in a given group.

Editor

Has permissions needed to access the Control page for managing the research objects they are assigned to.

This includes assigning other team members, inviting reviewers, editable access to metadata and decision/evaluation data as well as the ability to edit task lists and communicate with all stakeholders.

All research objects assigned are listed on the Dashboard→Manuscripts ‘I’m Editor of’ tab.

Reviewer

Has permissions needed to review the research objects they are assigned to. This includes access to the Review page and review form, and the ability to communicate with the editorial team.

All reviews assigned are listed on the Dashboard→To Review tab.

Author

Can access and manage the submissions they have created or are associated with.

Authors can submit multiple versions of research objects and/or datasets and communicate with the editorial team.

All submissions are listed on the Dashboard→My Submissions tab.

The easiest way to get started with workflows in Kotahi is to use a preconfigured group template. But for fully custom workflows, mapping desired processes to Kotahi's configuration is key. Here are some tips.

Hierarchical vs flat community workflow

Kotahi allows configuring hierarchical roles or a flat community structure - it's flexible to fit different needs. By default, it separates Authors, Reviewers, and Editors into distinct roles. However, a flat hierarchy can be enabled in Settings → Configuration by checking ‘All users are assigned Group Manager and Admin roles’. It is also possible to manually make users Group Managers or Admins via Settings → Users which may assist if you want a ‘mixed’ model.

In flat communities where all participants can see everything, it also makes sense to set the Manuscripts page as the landing page upon login. This is configured in the ‘Landing page for Group Manager users’ dropdown.

With these simple tweaks, Kotahi can be adapted from hierarchical journal workflows to flat, open review communities. The roles and permissions model is customisable to enable varying levels of openness and transparency. You can craft optimal settings for your reviewers and authors to collaborate.

Review model

A key component in configuring the review model is customising the Review Form under Settings → Forms → Review.

This flexible form builder allows the creation of any desired structure for reviews, including custom rating systems. For example, you can add a ‘Select’ form element and use HTML star codes to easily build a 5-star rating selector. The possibilities are extensive - add text sections for comments, numeric scales for ratings, multiple choice questions, and more. Granular customisation of the Review Form enables tailoring the process to fit your evaluation needs. And helpful features like metric selectors and star ratings make it simple to collect key quantitative feedback. With full control over the form, you can craft an optimal review experience for your community.

Further, you can set up various kinds of review process.

Single blind

When authors are visible to the reviewer, but the reviewer is not visible then this is managed from the Control page for each research object by selecting ‘Hide reviewer name’.

If ‘Hide reviewer name’ is selected, the reviewer's identity is anonymised;

• when submitting (sharing) Decision/Evaluation form data with the author

• on the Review page if a review is set to ‘Shared’ with other reviewers

• on the publish action when publishing to Flax

  

Double blind

In the case of a double-blind review where both the authors names and the reviewers name are hidden from each other, use the setting above to hide the reviewer name.

Second, selectively hide author names from reviewers. Under Settings → Forms → Submission, any form components that display author details like names, affiliations or the MansucriptFile, should have 'Hide from Reviewers?' selected.

Lastly, from the manuscript or production editor, you will need to delete the author names from the manuscript.

This obscures manuscript-identifying information from reviewers to complete the double-blinding. Between hiding reviewer and author details, you can easily implement fully anonymous peer review.

Open review

The identities of the authors and reviewers are known to each other. In which case, don’t hide the authors fields from reviewers in the submission form, leave the author names in the manuscript, and share the reviewers name from the Control page settings.

Collaborative review

Reviewers can discuss the submission together and collaborate on a review. This can be moderated or unmoderated and is managed at the moment you invite a reviewer by selecting ‘Shared’.

Only reviewers with ‘Shared’ enabled can see each other’s reviews on the Review page.

The option to enable collaborative reviewing is kept as a manuscript-level setting rather than global, to allow flexibility in mixing collaborative and independent reviews. For example, you may want 2 reviewers to collaborate on one manuscript while 2 others write independent reviews on the same submission.

This granular control makes it possible to have a hybrid approach within the same journal or collection. You can choose collaborative reviews when you want reviewers to discuss and consolidate feedback, while independent reviews give you multiple perspectives.

The per-manuscript configuration provides the most flexibility to tailor peer review based on the needs of each submission. You can determine the optimal individual vs collaborative review structure case-by-case.

Community self-review

For peer review models where the community self-selects to review manuscripts, enable access to submissions under Settings → Configuration and check ‘All users are assigned Group Manager and Admin roles’. This will make the Manuscripts page visible to all users, allowing community members to freely choose papers to review.

This facilitates review without editor assignments. Reviewers can simply pick submissions of interest to them and self-organise review efforts through the associated discussion.

The chat on the Manuscripts page provides a space for transparently coordinating who will review each item. Community members can claim papers, avoid duplication of efforts, and fill gaps.

With accessible manuscripts and integrated coordination tools, Kotahi can effectively support open self-selected peer review. The platform enables the community to democratically manage the process from paper discovery to discussion.

Multiple rounds

You can have as many iterative rounds of review as needed with the same or new reviewers each round (typical for Journals). A new round is started by submitting a decision to revise from the Control page.

Rolling submissions

Authors can update submissions during an active review round if enabled (this has proven useful for some preprint review use cases). You can enable this by checking Settings → Configuration → Allow an author to submit a new version of their manuscript at any time.

Workflow status

The submission form builder can be used to create tools to manually update and monitor the status of research objects as they are being processed. To do this, you can use the ‘Select’ form element (see above) to build a drop down menu outlining the processing stages. You can have any number of states, and additionally, the form builder enables you to choose a colour per state should you so wish so you can easily understand state at a glance.

This status display can be included in the Manuscripts page as a colum if you so wish by adding the internal name to the comma-separated list in Settings → Configuration:

Kotahi also has automated generic states that can also be included in the Manuscripts page by adding ‘status’ to the same list.

It is also possible to display the state tracker to the Control page by adding it to the decision form in a similar manner.

Taxonomy / Groups

Kotahi allows creating customisable taxonomies or groups for research objects using the ‘Select’ form component. These taxonomies are editable, so new types can be added as needed.

Including the taxonomy dropdown in the Manuscripts page columns provides filtering and grouping capabilities. Users can select a specific type from the dropdown to view only those matching objects. The filtered list URL can also be shared for collaboration.

For example, a group could contain types like ‘Type A’ and ‘Type B’. Filtering to ‘Type B’ would show all research objects in that group. The URL could be shared with others to coordinate efforts.

This enables segmenting objects in flexible ways - by status, priority, subject area, etc. Taxonomies help organise community work by creating specialist lists. And the ability to amend types supports iterative workflow design.

Deciding what to publish

There are many controls and settings in Kotahi to decide what you will publish. If you wish to publish data, for example, you may not need to supply a manuscript upon submission. In this case, you can hide the page displaying the manuscript from view from Settings → Configuration

You can also decide what data will be published when setting up the submission form. Each element has the option as follows:

Publishing evaluations / reviews

The review and decision forms in Kotahi can be fully customised using the form builders. This enables granular configuration of what data is captured in the review and decision processes.

Using the form builders, you can:

• choose which review and decision fields are shared or published, and which remain internal

• decide if full verbatim reviews are published or if curated excerpts are preferable

• determine if overall decision summaries, reviewer recommendations, or any other custom fields are disseminated

• select specific metrics like ratings or scores for publication rather than full text

• opt to only share the decision outcomes such as ‘accept’ or ‘reject’ without additional details

• hide reviewer identities from the published decision data as needed

The review and decision form builders allow optimising the data workflow - controlling what reviewers provide, limiting internal-only data, and configuring the published evaluation content. This enables sharing evaluations in customised formats, from high-level decisions to granular, transparent assessments. The system accommodates community preferences in determining what aspects of the process to openly disseminate.

Formating

Kotahi offers extensive formatting flexibility when publishing content internally to its built-in CMS. The research object can be laid out and styled in any desired way, including custom components like data visualisations.

The internal CMS enables complete control over publication formatting. Content can be structured with sections, styled with CSS, and enriched with multimedia embeds as needed. Articles, data, code, images, and other supplementary materials can be tightly integrated.

For example, a published preprint review could contain the full community discussion threaded directly alongside curated recommendations. Interactive graphics could also enhance understanding of the analysis.

While publishing externally limits format control, the internal CMS provides limitless customisation possibilities. Creative publishing styles can truly amplify the value of the research object.

Tasks

The Kotahi task manager is a powerful workflow design and management tool worth investing time into. Tasks allow granular mapping out process steps, ordering, notifications, and roles.

Rather than just tracking tasks, the manager can be leveraged to actively conceptualise ideal workflows. The customisable main task template essentially serves as a blueprint for iterative workflow design.

As workflows evolve, the template can be modified to reflect new processes. Additional ad hoc tasks can also be added to individual objects as needed. This balance of structure and flexibility enables both workflow standardisation and handling unique cases.

Key benefits of the task manager:

• visualise and conceptualise workflows through customisable templates

• promote consistency via predefined task sequences

• enable flexibility for per-object adjustments as needed

• set notifications to coordinate community members

• refine tasks continually as workflows improve

• combine global templates and per-object adjustments

With powerful abilities to model workflows plus adapt them over time, the task manager is a valuable design asset. Investing in its configuration pays dividends for conceptualising, communicating, and continually improving publishing processes.

There is much more to designing and setting up your workflow. Kotahi enables you do do so much that most of what is possible hasn’t even been considered yet! The best thing is to experiment.

The submission form builder allows you to customise submission forms to fit your workflow needs, whether ingesting metadata (from, for example, preprint servers) or accepting direct submissions. While it may not seem powerful at first glance, the form builder is actually a versatile tool for configuring workflows.

The power of the form builder lies in its ability to streamline gathering the metadata you need from authors. Forms can be carefully designed to optimise completeness, accuracy and user experience during submissions. For instance, you can craft forms that ensure authors provide all required information in a clear and easy-to-follow format.

In addition, the form builder lets you create different forms to support various submission types and sources. A preprint ingestion form pulling metadata may need only a few key fields, while a direct author submission form for a micropublication format would require more granular data, and a full journal submission form would possibly require even more comprehensive details. The form logic allows you to customise for each workflow.

The form builder and the data lifecycle

The Kotahi form builder enables innovative and powerful configuration options that can optimise the entire submission data lifecycle. The most powerful of these features include:

Hide from reviewers - Fields can be hidden from reviewers to control the metadata they see during the review process. This allows optimisation of the data profile for review.

Hide from authors - Form fields can also be hidden from submitting authors, for example, to capture data such as submission IDs without the author seeing it.

Include at publication - You can configure which fields are shared or published, and which remain internal only.

These form builder concepts allow granular control over the submission data workflow:

• what authors provide

• what reviewers see

• what is made public

With strategic use of these capabilities, you can streamline submissions for authors, tailor review data, and determine publishable metadata - all from one form.

This flexibility and customisability within a single form builder interface demonstrates why it is such a versatile submissions tool. You can optimise the entire submission data lifecycle.

Getting started

To access the submission form builder, use the left menu → Settings → Forms. With some planning around your goals, the form builder allows you to build submission forms that truly enhance your workflows. It may not seem like a powerful tool initially, but the form builder offers extensive ability to optimise and streamline submissions.

The submission form builder provides all the necessary tools to create one or more submission forms. As mentioned above, Kotahi supports both automated creation of submissions (e.g. by ingesting preprint data using AI) and manual submission creation. Regardless of method, a submission form is required to hold metadata for research objects. For automated ingestion, fields can be auto-completed. For manual submission, authors/researchers must fill in the form data themselves.

In the image above you see a already-completed Submission Form Builder. On the left you see a list of form elements, on the right is the information about each element.

Building a form

To start taking advantage of the submission form builder, I recommend beginning to build a form for your particular use case. A benefit of Kotahi is that you can easily do this in a new tenant without affecting any existing workflows you have already configured.

Some tips on getting started:

• make a plan of the key metadata fields and submission information you need authors to provide. Organise these into logical groups or sections.

• look at forms you currently use and think about areas that could be improved or streamlined in Kotahi.

• start by building a simple prototype form in a test tenant. You can iterate on it and add complexity over time.

• use Kotahi's flexible form widgets like descriptions and tooltips to optimise the author experience.

• don't worry about getting it perfect right away - tinker and tweak as you learn. The form builder makes it easy to enact changes.

The key is to dive in and start building a form for your workflow. Kotahi makes it low-risk to experiment and learn. Taking an iterative approach allows you to progressively improve the form to best fit your needs.

Starting a new form

Let’s look at a new form and start breaking apart the interface. In a new form you will see the following.

On the left is the button to add a new field (form element), and on the right is a basic description for your form. Fill out the information on the right with placeholder or actual data (you can always change it later) and click ‘Update Form’.

Now click ‘+Add Field’, you will see something like the following.

On the left you see a placeholder list item, on the right you see a new box titled ‘Field Properties’. The Fieldtype dropdown within this box enables you to choose what kind of form element you want. Currently, the choices are:

1. ManuscriptFile

2. SupplementaryFiles

3. VisualAbstract

4. AuthorsInput

5. LinksInput

6. AbstractEditor

7. TextField

8. CheckboxGroup

9. Select

10. RadioGroup

When you choose one of these types then the page will display options for that element.

Adding your first element

Starting with something simple, let’s choose to create a ‘Select’ element (dropdown menu).

Let’s look at each of these controls.

1. Field type - the type of element (‘Select’ in this case).

2. Field title - the name of your field as it will appear in the rendered submission form.

3. Name (internal field name) - Name (internal field name). This metadata identifier is important for integrating the form data throughout your workflow. Use a format like ‘submission.yourFieldNameHere’. For example, ‘submission.preprintServer’ if collecting the preprint server name.

   The submission prefix carries the field through to other processes like generating JATS XML, publishing with the Kotahi CMS, or sending data to external systems.

   With some planning on field names, you can efficiently pull form data to where you need it later. See the documentation for more on how naming conventions enable workflows. The key is to think ahead on how you want to utilise the information collected in the form.

4. Field placeholder - prompt the user through the user of informative text that is visible in the form field text editor.

5. Field description - a full text explanation (if required). This description is displayed below the field when submitting.

6. Field options - allows additional configuration specific to each element type added to the form. For a Select input type, Field options let you build the list of items available for users to select from in the dropdown menu.

   To create the select options, first click ‘add another option’. You can now add one option per line in the format of ‘labelvalue’. The label is what users see in the dropdown, while the value is the internal metadata identifier that will be saved when an option is selected.

   For example you could have:

   Preprint Server A | preprintServerA

   Preprint Server B | preprintServerB

   This clearly labels the select options for users, while saving standardised values for the back end. You can also choose a colour for the section if required.

   Once the options are defined this way in Field options, they will populate the select dropdown. When users make a selection, the corresponding value will be captured as the submission data.

   Using Field options allows tailoring the Select input type with customised dropdowns that fit your metadata needs.

7. Short title (optional — used in concise listings)

8. Validation options - you can choose ‘Required’ if you wish this to be a required field.

9. Hide from reviewers? - here you can specify if the reviewers should this data on the Review page. In this way, you can use the form builder to determine the data profile of the research object which is visible for review.

10. Hide from authors? - you can decide if the field will be visible to the submitting author (if applicable).

11. Include when sharing or publishing? - Kotahi supports selective publishing and this option enables you to determine the data you will share at publish time.

Once you have completed all items press ‘Update Field’ and this will be recorded. You can now add more form elements and build up your submission form. See the documentation on each element.

Support for multiple submission forms

Currently, you can create multiple submission forms but only a single form can be selected for use. Only the Form purpose identifier field populated with ‘submit’ will be available to authors.

You can build your own reviewer form through the form settings. Tailored reviewer forms focus the process, reduce fatigue, provide guidance, collect consistent structured data, and adapt over time. This ultimately leads to more robust, useful reviewer feedback and analytics.

To get started choose Settings→Forms→Review.

The above image shows a completed reviewer form. Building a review form is essentially the same process as building a submission form (see documentation).

It is important to note that Kotahi enables individualised and shared reviews. These two options are not controlled here (see documentation on reviews).

Support for Multiple Review Forms

Currently, you can create multiple review forms but only a single form can be selected for use. Only the Form purpose identifier field populated with ‘review’ will be available to reviewers.

The decision/evaluation form builder allows customisation of the controls on the Decision tab in the manuscript review interface. This enables capturing nuanced details of your evaluation workflows.

The form builder provides advantages such as:

• adding custom fields related to the decision itself, like evaluation criteria ratings, rather than just a basic accept/reject choice

• incorporating additional metadata fields beyond the core decision, such as status markers, that relate to workflow steps

• guiding editors/curators to provide structured inputs through smart form design, rather than just freeform comments

• collecting consistently structured data across all decisions for better reporting and analytics

• adapting the decision inputs over time by altering the form fields to fit evolving needs

• streamlining the decision process by focusing inputs on what's most relevant

The flexibility to customise the editor/reviewer decision form allows the creation of optimised workflows for evaluation. This moves beyond basic decisions to gather meaningful metadata that informs the publishing process.

To get started, choose Settings→Forms→Decision.

The above image shows a completed decision form. Building a decision form is essentially the same process as building a submission form (see documentation).

Support for multiple decision forms

Currently, you can create multiple submission forms but only a single form can be selected for use. Only the Form purpose identifier field populated with ‘decision’ will be available to editors.

Furthermore, if your workflow supports a decision of ‘Accept’, ‘Revise’ and ‘Reject’ then you can use a RadioGroup form field type, set the Name (internal field name) to ‘verdict’ and configure the settings as follows;

• selecting ‘Accept’ will enable the ‘Publish’ action

• selecting ‘Revise’ will allow the author to submit a new version

• selecting ‘Reject’ will disable the ‘Publish’ action

You will need to set the Name (internal field name) to ‘verdict’ to enable this functionality.

The task configuration in Kotahi is an extremely powerful yet often underestimated feature. Defining tasks is not just a to-do list but rather it is where you can further optimise and customise your editorial and publishing workflows.

In Settings→Tasks you can set up a template for tasks that will be inherited by all research objects submitted.

Strategic task configuration unlocks benefits like:

• mapping out clear step-by-step workflows for different types of research objects

• automatically prompting editors/curators, reviewers and authors to complete important actions

• improving transparency by providing visibility into workflow status

• identifying workflow bottlenecks

• adapting workflows over time by iteratively improving task definitions

• standardising workflows across users by assigning the same task lists

With some upfront planning around aims, the flexible task engine enables enacting efficient, consistent, and customisable workflows in Kotahi. The tasks truly represent a powerful yet often overlooked opportunity for workflow optimisation.

How to make task templates

The initial task list for the research object will be inherited from the task list set up in the system settings (see that section). It is also possible to add/delete/alter the inherited list to suit the needs of the specific research object.

Tasks can be created, edited, deleted, modified, started, and reordered from this interface.

Starting a task is done from the displayed ‘Start’ button.

Adding tasks is done via the ‘+’ button at the bottom of the task list.

Adding a title and adding an assignee can all be done via the input fields provided. The assignee dropdown displays a list of roles, and the full searchable list of users in the system for selection.

Duration (in days) can be managed via the duration field.

Deleting or editing of the tasks can be managed through the ellipses icon displayed between the task title and the assignee.

Deletion will ask you for a confirmation before completing.

When editing a task, the overlay for that task will appear.

Duration can be changed from the Due Date item on the left. When clicked it will display a date picker where you set a due date.

Clicking Add Notification Recipient will display an interface for adding new recipients of notifications. You can add as many recipients as you like.

The input fields require a chosen recipient from the Recipient dropdown list. You can also add a recipient that is not registered in Kotahi by choosing ‘Unregistered user’ from the dropdown. This selection will display additional fields for the email address and name of the recipient.

You can also Select an email template to be sent to each recipient.

Next set when the notification is sent out. The notification can be sent at a time of your choosing (including ‘now’) relative to the due date of the task. The Send notification fields allow you to choose a time before or after the due date by the number of days you require.

Email notifications are only sent when a task status is In progress. To enable a task, click on the Start action. A task that is ‘Paused’ or marked as ‘Done’ will suppress scheduled email notifications from being sent. Notifications can still be manually using the ‘Send Now’ from the overlay.

Special actions

We are adding further controls to the task manager as we believe it has enormous potential. Two important actions already possible from the task manager are inviting authors and inviting reviewers. You can action these from the notification controls. Inviting reviewers will add the reviewer invitation to the research objects reviewer list (accessible from the Control page). Inviting authors is for inviting an author to join a submission if that submission was automatically ingested (useful for some preprint review workflows).

The ‘Task notification’ email template contains a hyperlink that will direct the user to the manuscript task list. This can be particularly useful for editors who wish to be reminded of upcoming task deadlines.

Users are managed from Settings→Users.

Here you see a list of all users in the system. The users are listed with the following information in columns:

• Name - the full name of the user (with a picture if provided by the user in their profile page)

• Created - the date the user created an account

• Last Online - when the user was last online

• Roles - the role(s) they’re assigned

• Delete - deletes the user from the system (requires a confirmation)

All columns are sortable by clicking the column title.

Roles

There are two roles you can set at this interface that have to do with the administration of the system - Group Manager and Admin.

• User - a user assigned either as an author, reviewer and/or editor in a group

• Group Manager - has permission to access all group pages listed in the menu, essentially a ‘Group Admin’ role

• Admin - has access to all groups on an instance and has limited access to group pages

This page shows general settings for configuring many aspects of Kotahi. To access this page choose Settings→Configuration.

There is a lot here! Let’s go through the controls one by one, top to bottom. This will be a long story as there is some context that we need to give for some of the items.

Instance type

Kotahi can be configured to meet many types of workflows and use cases (see section titled ‘Pre-configured workflows’). What is also very powerful is that Kotahi comes with some preset configurations you can choose from. We call these ‘archetypes’. Typically you cannot change this setting for a group (tenant) in Kotahi once it has been set by the administrator. However, you can create as many groups as you like, each with its own archetype. Instance types are set by a developer via the system configuration (.env) file.

It is also possible to create a workflow and save it as a template but at this moment you will need a developer to do this for you.

Instance types at the moment include:

1. aperture - a typical Journal workflow

2. colab - a PRC workflow

3. elife - submit, review and publish from a single form

4. ncrc - submit, review and publish from a single form, and import preprints

Group identity

Enables you to set basic branding for your group.

Brand name - this enables you to set the name of the group. The group name is displayed in a dropdown menu at login time for installations with multiple groups.

Brand primary color - used for the left hand menu, some buttons, and title texts.

Brand secondary color - used for additional highlighting.

Logo - the logo for the group. At this moment there is no manual upload.

Dashboard

In Kotahi, you can change the landing page for users as the first page they arrive at after they log in.

The Landing page settings allows you to choose from either the Dashboard or the Manuscripts page as the landing page. The Dashboard is probably the most common use case but in flatter hierarchies, the entire community may wish to have access to the manuscripts page. We have found this to be the case for small groups working together or some preprint review communities.

You can additionally choose which tabs are displayed on the Dashboard. Your choice here is also reflective of your use case. If you are a Journal group, then you probably want to select all three items. If you are a community that reviews preprints that are automatically ingested, you may wish to only display the ‘To Review’ item etc

Manuscripts page

Here you have some great options for configuring the Manuscripts page.

1. List columns to display on the Manuscripts page - you can configure the columns displayed on the Manuscripts page. This is actually more powerful than you might think. It is possible, for example, to create a form element in the submission form builder for the selection of workflow status from a dropdown. This can then be displayed as a column on the Manuscripts page and effectively functions as a workflow tool. There are many other possibilities and experimentation is key. Columns are added using the comma-separated internal fieldname fields for each form element added in the submission form (you can hide these elements from submission and review forms if required via the form builder controls).

2. Number of manuscripts listed per page on the Manucripts page - this controls the number of items displayed as a list (pagination controls).

3. Hour when manuscripts are imported daily (UTC) - this is a setting for the AI importing of preprint metadata. Currently set up for the AI integration requires a developer but you can use these settings to control how it works once set up.

4. Number of days a manuscript should remain in the Manuscripts page before being automatically archived - if you are auto-ingesting manuscripts, you might get a lot of ingested items and not be able to get through them all in the time window you desire. This option gives you the ability to auto archive those ‘expired’ items if required.

5. Import manuscripts from Semantic Scholar no older than ‘x’ number of days - when auto-ingesting preprints via AI you can specify the maximum age of the preprint. This helps preprint review communities discover the latest preprint materials for review.

6. 'Add new submission' action visible on the Manuscripts page - displays the button to start a manual submission from the Manuscripts page. This is useful for many use cases, it has been used to enable preprint review communities that have automated ingestion of preprints to also add an item manually.

7. Display action to ‘Select’ manuscripts for review from the Manuscripts page - ‘Select’ is a triaging feature, especially useful in conjunction with bulk imports. It changes the 'label' field to ‘Ready to evaluate’. Filtering and bulk deletion can be used in conjunction with these labels. It is also used for feeding AI selection criteria in some use cases.

8. Import manuscripts manually using the 'Refresh' action - this will put a ‘Refresh’ button on the Manuscripts page so you can manually start the auto ingestion process.

Control panel

This setting group enables you to configure various items on the Control page.

1. Display manuscript short ID - each research object has a unique ID given to it by Kotahi. This is an ‘internal’ identifier largely just used so users can discuss or find the item easily. Checking this item will display the relevant manuscript ID on the Control Panel for each research object.

2. Reviewers can see submitted reviews - set if you wish reviewers to see each others’ reviews. If not checked, reviewers can see only their own review.

3. Authors can see individual peer reviews - if checked, authors can see the entire review for each reviewer.

4. Control pages visible to editors - you can hide various tabs if they are not relevant to your use case.

Submission

There is one item - Allow an author to submit a new version of their manuscript at any time. This setting determines if an author/submitter needs to wait until the beginning of a new review round to submit a new version of their manuscript and metadata, or alternatively, if checked, the author can submit at any time (even mid-review). This has been used by preprint review communities where the review process (Kotahi) and submission system (a preprint server) are decoupled.

Review page

This setting determines whether Reviewers can see the decision/evaluation information.

Production

Settings relevant to the Production page include controls to configure output when using the ‘Reference’ parser.

Publishing

Settings related to some specific publishing endpoints. This may or may not be relevant to you. Essentially, if you are publishing preprint reviews to some external services the way in is via the hypothesis API.

Crossref

API information and controls for accessing Crossref.

Webhook

This section enables you to set a webhook for publishing to an external endpoint.

Publishing webhook URL - the endpoint or target for the publishing action supplied as a URL

Publishing webhook token - the secret token used to authenticate the exchange

Publishing webhook reference - data sent to the target to know how to process the information

Task manager

Here you can set the timezone for the date picker when setting tasks.

Emails

Configuration for the account information through which Kotahi will send emails. Currently, only Gmail is supported. These instructions outline the correct Gmail password to use when configuring your account.

Event notifications

Configuration options for sending email notifications. Each workflow type has supporting events, and the option to assign an email notification

1. Reviewer rejects an invitation to review - choose from the email templates for the email to be sent to the reviewer when they reject an invitation to review.

2. Reviewer invitation - set the email to be sent to the reviewer when they are invited to review.

3. Submitted review - set the email to be sent to the reviewer when they have submitted a review.

4. Submitted manuscript - choose the email to be sent to the submitter when a research object is submitted.

5. Unread discussion message - choose the email to be read when messages are remaining to be read in a chat for all users.

6. Immediate Notification for users @mentioned in a message - choose the email template to be sent when a user is @ mentioned in the chat.

Reports

Settings to show or hide the reports page from the menu.

User management

One interesting user setting and a misplaced API key setting

All users are assigned Group Manager and Admin roles - essentially gives you a flat community hierarchy in which all users can access all pages in the menu and see all parts of the process.

Kotahi API tokens

A setting for the Kotahi API to be used by external applications.

You can view all email notification templates here. All templates appear as options to assign in the event in the Configuration manager, recipients in the Task manager and when sending an ad-hoc Notification.

Changes, deletions and additions to email templates currently need to be done by a developer (about to change shortly).

A list of short codes that can be used include:

1. {{ currentUser }} - the person that sent the message

2. {{ recipientName }} - the recipient name of the email

3. {{ discussionUrl }} - a direct link to the discussion (if applicable)

4. {{{ acceptInviteLink }}} - generates a direct link to accept an invitation to be associated with a research object as an author

5. {{{ declineInviteLink }}} - generates a reject link to a invitation

6. {{{ manuscriptLink }}} - link to the research objects submission

Kotahi offers configurable publication options, including an internal CMS. Content can be published to the CMS, external endpoints, or both.

The Kotahi CMS design follows the principle: ‘Make simple things simple, and complex things possible.’

The CMS interface enables straightforward management of basic websites and content publishing. This simplicity makes routine tasks easy.

However, the CMS also provides tremendous flexibility to customise sites. It can be structured to function as a journal publishing platform, a preprint server, a micropublication repository, a preprint review publisher, or virtually any model required. With some configuration, the Kotahi CMS can handle highly specialised and structured content. Its versatility supports diverse scholarly publishing needs.

The CMS balances simplicity for basic use cases with extensive customisation potential for complex requirements. Teams can start simply and then evolve the CMS as needs grow. This range encapsulates the design principle driving the system. The CMS aims to make simple things simple while enabling complexity when required.

The CMS interface is provided for creating simpler publishing sites easily. You can locate the controls under Settings→CMS. If you choose the first of the items (‘Pages’) below the CMS selector, you will see the following.

Create new pages here and edit them with the editor provided.

To add a new page, click the ‘+’ icon. The page won’t be added to the publishing site until you include it in the menu and choose to publish it. You can publish pages by clicking on the Publish action.

You can fill out the new page title, the ‘stub’ (effectively the URL the page will appear on), and then add the initial content. The editor also supports image insertion.

Layout

Layout of the page is accessed by clicking ‘Layout’ in the CMS menu.

Here you have some basic settings for the brand, uploading a logo, and selecting a primary and secondary color.

Header

In the Header section, you can control the menu. The header section appears on every page. Pages ordered top to bottom are displayed from left to right as links in the header. Only selected pages are displayed when published.

Footer

In the following options, you can configure what appears in the footer, starting with partner logos and associated website link. Footers are displayed on all pages.

Next you can set the footer text.

Lastly you can include links to additional pages in the footer (possibly items not in the topmost menu).

When you press ‘Publish’, the updated settings will be pushed to your publishing site.

The Kotahi CMS is an Agile Digital Content Platforms (or ACP* for short), better known as 'static website generator' or 'headless CMS'. ACP’s are a game-changing solution. With an ACP, publishers define the logic and organisation of their content using plain text files. This paradigm escapes the 'hard-coded' and predefined logic imposed by a GUI, and allows for enormous flexibility for publishers wanting to tailor their content's structure, design, and functionality.

ACPs are not new in the web world. There are plenty of these tools available, the most popular of which are probably 11ty, Hugo and Jekyll.

ACPs are also not new in the publishing world, but usage in this domain is relatively rare. The rarity in publishing is due largely to legacy thinking and narratives from incumbent vendors that are heavily invested in their own technology. Consequently, most publishers think that a traditional CMS is the only way there is to present their content. Not so. The British Medical Journal has used the ACP approach, so has the Getty, and you can also have a look at a recent work by the Louvre made by Coko's ACP - FLAX (built into Kotahi). The scope illustrated by these projects, built by prestigious organizations, should tell you that the ACP approach is mature and mission-ready, as well as giving you some idea of the flexibility of content presentation that can be achieved.

*Agile Digital Content Platform is a term used in this article for the purpose of better explaining this technical category to publishers. Many thanks to Christian Kohl for the name.

How it works

As an example, let's look at the Kotahi CMS developed by Coko for publishing use cases, built on top of 11ty (an approach also adopted by the Getty).

With the Kotahi CMS you edit text files that allow you to define three principle items - your data, your content, and your layout. There is more to it than this, but this idea is central to the design.

By way of example, let's consider creating an 'About' page for a journal. This process involves creating a simple text file as follows:

Let's dig into a brief, lightly technical, explanation. In the file above, the section between the --- lines is known as the front matter. It defines variables (title, description, and last_updated). The content following the front matter is the content of your 'About Us' page.

Alongside the this you would also have a template file which defines a layout for your page:

In this template, the Advanced CMS Use, , , and parts are placeholders for your data as you already defined in the first file.

The Kotahi CMS interprets the 2 files, processes the variables, applies the templates, and generates static HTML files (HTML files on a server).

For our 'About Us' page, the output would be:

Your users would then see the above HTML rendered as page in their browser.

This is an obviously over-simplified example - there is enormous additional sophistication to be had via API integrations, calling external databases, plugins, Javascript, CSS etc - but it gets across the basic principles.

Core to the paradigm is the idea that you can provide any data you want, and surface it (and your content) in any kind of structure you want, as described using just text files.

Furthermore, because the entire system is defined simply by a bunch of text files, you can expose the directory tree to the user (which contains these files), giving the user full control over the way their content is presented.

Advantages

The use of the Kotahi CMS instead of a traditional CMS provides many advantages:

1. Independence from CMS constraints: You're not tied to a particular CMS's complex, opinionated, codebase and predetermined constraints.

2. Flexibility: You have enormous flexibility to define the structure, design, and behavior of your publishing front end.

3. Ease of Use: Even with its high customisability, only a minimal amount of technical knowledge is required to build your content portal using this approach.

4. Lightweight and Efficient content delivery: ACPs generate static HTML files, leading to fast-loading pages and enhanced website performance. This is especially beneficial for users with slow internet connections or when your site experiences high traffic. This is also incredibly cheap when it comes to hosting costs as opposed to the hosting costs of a heavy duty CMS.

Publisher autonomy

One further, major, advantage of this approach is that it liberates publishers from dependency on third-party software vendors for altering the CMS's internal logic. Traditionally, such alterations can be costly and time-consuming, leaving publishers at the mercy of software vendors. Particularly with proprietary software vendors, publishers have limited options but to request or pay for changes. Even when successful, the process of incorporating those changes is often protracted, as the vendor has to modify their code base's internal logic to accommodate the publisher's requirements.

In contrast,the Kotahi CMS allows publishers to collaborate with any technician - be it an in-house staff member or a local web developer to make these changes by simply editing text files. The required skill set falls within the web development realm, which is a more accessible and cost-effective field compared to traditional programming.

In essence, this approach provides publishers with an escape route from vendor lock-in, granting you greater autonomy and flexibility in managing and customising your content.

Getting Stuck In

To move ahead with advanced Kotahi CMS use it is best to join the support channel at Coko and start talking to the folks there. At the moment this level of customisation is not covered in this manual.

The Kotahi Production interface is designed to radically reduce the cost and time for producing various formats such as HTML, PDF and JATS (XML). It can also be used for author proofing.

The interface is simple but powerful. In the production editor, you will see the manuscript displayed. This is entirely editable. On the right we see a download dropdown menu.

From this dropdown menu, you can select PDF, JATS and HTML. PDF is generated using Paged.js (see documentation). JATS is created automatically by Kotahi and validated. HTML comes straight from the content displayed in the editor.

If you wish to improve the granularity of the JATS files you produce, you can use the tools on the left menu (see JATS documentation in this manual).

When using the production interface, the team can check the citations and improve them with the assistance of Kotahi’s automated citation tools.

To access these tools, view the research object in the production interface (linked from the Manuscripts page) and scroll down to the reference list.

On the left, you will see a reference tool:

Select an item in the references and then click on this reference tool. You will see a menu appear to the right of the reference.

Clicking on one of these icons will display an overlay.

Here you see a list of possible citations based on the information in the original citation. The recommended citations come from a variety of sources (more can be added). Native to Kotahi 2.0 are AnyStyle and Crossref sources.

You can now choose one of the citations displayed (these also conform to the citation format set in the Kotahi system settings).

You can also select one of these citations and click ‘edit’ and a further box will display for editing that selection.

This service relies on 3rd party APIs to generate results. These services may be disrupted from time to time. You may need to re-run imports if this service does not generate results as expected.

Settings to change the citation style and other related controls are located in the Configuration→Production section.

JATS is the Journal Article Tagging Suite. It is an XML format used to describe a journal article.

Creating XML is usually done via inhouse technical staff or outsourced to a publishing vendor. This generally increases the costs for processing articles and slows down the time to publish.

Kotahi has inbuilt tools that enable you to create high fidelity JATS output at the press of a button and with no technical expertise.

The production editor includes features related to creating JATS.

The user requires no prior knowledge of JATS or XML to prepare the document for JATS export. The interface simply requires the user to highlight parts of the document and choose what type of content that selection contains from the tools in the left menu. This is very much a drag-and-drop and point-and-click exercise. No messy editing of XML required.

The Production editor then marks the underlying format (HTML) in such a way that Kotahi can map these tags to JATS at export time.

The following annotations can be applied in the Production editor;

• Front matter - Abstract, Funding group, Funding source, Award ID, Funding statement, Keyword list and Keyword.

• Back matter - Appendix, Acknowledgements, Glossary Section, Glossary term, Reference list and Reference (parser).

Both Manual and Automated Submissions can be made in Kotahi. This chapter covers manual submissions, please also see the appropriate section on Automated Submissions.

Manual Submissions are made from your Dashboard.

When you click the ‘+ New Submission’ button you will be presented with a new screen:

There are two basic methods to create a submission:

1. Upload Manuscript - by clicking ‘+Upload Manuscript’ you can choose a research object to upload. The types of filetype accepted depends on the configuration of your group.

2. Submit a URL instead - by clicking on this you can simply add a URL as a submission (good for preprint reviews or submitting dynamic notebooks, code repositories, online data sets etc)

Upload manuscript

There are two major categories for Upload Manuscript:

1. Selecting a docx - in this case, the MS Word file is ingested into Kotahi and can be viewed and edited in the manuscript editor.

2. Selecting another filetype - in this case, the manuscript is treated as an attachment.

Entering submission data

After you have uploaded a manuscript (or provided a link) you will be automatically redirected to the Submission page:

Note, the page displayed in this image is an example and may differ from how your Submission page looks.

You can now enter data to fill out the submission form. It is also possible to toggle between the manuscript and the submission data by clicking on the tabs ‘Edit Submission info’ and ‘Manuscript text’).

When you have entered all the data press ‘Submit your research object’. You may be prompted to complete a Terms & Conditions/disclaimer before submitting.

If you have been invited to review, you will have received an email.

The actual text of your email may differ from the above. The email invitation includes a link to accept the invitation and a link to reject the invitation.

If you choose to accept, then you will be asked to login and redirected to your Dashboard. In the ‘To Review’ tab you will see your item for review:

Clicking Do Review on the right will take you to the reviewing page for the item:

The page will differ depending on how your version of Kotahi has been configured. In this case, the display shows the full text of the article for review. Scrolling down will display all the relevant metadata, and further down are the areas where you can complete the review.

Again, the review form is entirely configurable so you will probably see something different to what is displayed in this image.

You may now complete the review form and submit your review. If you have not completed the review, you may come back to it at a later date and the content of your partial form will persist across sessions.

Depending on how Kotahi has been configured for you, you may be able to upload a PDF or other file that contains your review.

Kotahi's core design principle is that technology should support people and processes, not that people should serve technology. The platform aims to provide adaptable infrastructure for configuring publishing operations while giving users control to optimise over time.

This means Kotahi supports both streamlining established operations and experimenting with innovative models. Teams can use Kotahi to make existing procedures more efficient and pilot progressive ideas in parallel.

Easy reconfiguration of components like tasks, forms, and decision screens makes iterating processes seamless. Teams can continuously adapt approaches based on data and feedback.

With sandboxed multitenancy, Kotahi encourages trying new workflows with minimal risks. Fresh concepts can be tested without disrupting current operations.

At its core, Kotahi recognises publishing processes should be led by your needs not ‘how technology works’.

At a high level, many scholarly workflows follow a similar path - a research object is submitted, reviewed, improved, and shared. However, when examining the specifics, workflows that appear identical on the surface often diverge in their details. For example, while two projects may both conduct open peer review, one may rely on assigned editors while the other utilizes a flat (or flat-ish) community model. Or while two preprint review projects both automatically ingest submissions, their triage processes may differ significantly.

It's common for teams to state their needs are "quite simple" or their workflows are "pretty standard." But frequently, drilling down reveals unique requirements in submission steps, review processes, content types, and more. Standardized stages like "submit, review, improve, share" manifest differently across diverse fields and models. Assumptions of simplicity can obscure the intricacies involved in scholarly communication.

Thus it's important to resist perceived commonality and invest time to uncover granular needs. Workflow innovations often emerge from those subtleties. While patterns exist at a high level, the "magic" lies in the details.

The following is a self-help guide for understanding your current (if it exists) workflow and your ideal workflow.

Step 1: Understand the current workflow - this is necessary to generate an understanding of what you are actually doing right now. This step needs to drill down into the nitty-gritty of the daily workflow so you can get a complete picture of what actually happens ‘on the floor’. High-level executive summaries are not what we are after. We need to know what actually happens.

Without understanding exactly what you are doing now, improving what you do will be based on false assumptions. As poet Suzy Kassem has said:

“Assumptions are quick exits for lazy minds that like to graze out in the fields without bother.”

When examining workflow we need to bother people. To ask hard questions and get to the bottom of things. I’ve often heard folks say they know their workflow or that someone within their organisation knows the workflow. But after asking a lot of exploratory questions I inevitably find that no one person understands exactly what happens at all stages of the workflow. Consequently, understanding your current workflow, to the granularity required to move to the next steps, requires a process in itself. But we will discuss this in more detail in the next article.

However, Step 1, while important (and important to get right), is just prep for the most critical step of the entire process:

Step 2: Optimise the workflow - optimising the workflow is what every publishing technology project should aim to do. If you don’t optimise the workflow, if you haven’t improved what you do, then what have you achieved? It would make sense then, to prioritise thinking about improving workflow before you start to think about technology.

Optimising the workflow is, in itself, a design problem and requires dedicated effort. Unfortunately this step is often skipped or paid only a passing tribute. Conflating steps 2 and 3, for example, is typical of the popular publishing RFP (Request for Proposals) process (see https://upstream.force11.org/can‑we‑do‑away‑with‑rfps/) :

1. Understand the current (or speculative) workflow.

2. Design technology to enable the workflow,

3. Build (or choose) a new technology (optional).

An RFP process may be motivated by a few big ticket items that may need improving (or licensing issues as per above), but often lacks a comprehensive design process aimed at optimising the workflow. Instead, technology is chosen because it fulfills the requirements of the current workflow audit (Step 1) with a few possible fixes - this is because most RFP processes focus on updating technology rather than improving publishing processes. Consequently there are minimal, if any, workflow gains and a failed opportunity to identify many optimisations that can deeply affect a good technology choice and improve how you publish.

To avoid these problems and to improve how you publish, it is really necessary to focus dedicated design effort to optimising workflow.

The kind of process I’m talking about was once brilliantly described by Martin Thompson (Australian Network for Art and Technology) a long time ago. Martin was explaining the principles of video compression for streaming media, but the principles can be applied to workflow optimisation. Imagine a plastic bag full of air with an object in it (let’s say a book). The air represents all the time and effort required to produce that book. Now suck out the air, and we see the bag and book remain the same but the volume of air has reduced. We have reduced the effort and time to produce the book, while the book remains unchanged.

This is a simple but clear metaphor for what we are trying to achieve. In summary, optimising workflow is about saving time and effort while not compromising the end product.

Workflow optimisation requires an examination of every stage of the process (as discovered in step 1 of our workflow-first process) and asking if that stage can be improved or eliminated. We are also asking some other questions such as -

• Can anything be improved to help later stages be more efficient?

• Are there ‘eddies’ in a workflow that can be fixed?

• Can operations occur concurrently rather than sequentially?

When asking these questions, we will discover many efficiencies and we can slowly start drawing out a complete improved workflow. Some steps will disappear, some will be improved by mildly altering the order of operations, others will be improved by small tweaks. Some changes are more significant and may require greater change.

Once we have been through every stage looking for efficiencies, once we have our complete and optimised workflow, we are ready to start thinking about what we need to enable these changes. Technology may be part of the answer, but it is never the only answer, and in some cases it is not the answer at all. If we do decide new technology is required then only now should we start on the path to designing or choosing the tools to support our optimised workflow.

The most effective way to describe workflow is through a numbered list of who and what for each step, using WorkFlow MarkUp (WFMU).

There is no need to have complex flow diagrams and extended narratives - most of the time, these do not add clarity and sometimes mystify.

The three elements of WFMU are:

1. Who - usually the role of a team member or group (eg author, or editor). We use the naming convention of the host organisation for the role names. In some cases, the ‘who’ is an automation ‘role’ and refers to a machine (computer/s).

2. What - usually a single verb that describes what actually happens (eg review’, or ‘write’ etc).

The third part of documenting each step - When - is usually understood simply by the position in the numbered list.

An entire publishing process can be described in WFMU. Here is a short example:

1. Author creates a new Submission

2. Author completes Submission

3. Author Submits

4. Editor reviews Submission

5. Editor invites Reviewers

6. Reviewers accept (or reject) the invitation

7. Reviewers write reviews

8. Reviewers submit reviews

9. Editor reads reviews

10. Editor writes decision 1. If accept → publish (go to 15) 2. If revise → Author revises, return to (5)

Documenting workflow like this is straightforward to create and easy to read.

WFMU enables us to easily identify where problems exist. For example, if we saw this:

4. Editor reviews Submission

5. Editor invites Reviewers

6. Reviewers accept the invitations (or reject)

7. Editor considers a possible desk rejection

We can easily see a problem – we have just spent a lot of time inviting reviewers for a submission (Step 5) that might be rejected (Step 7) before reviews are written. These kinds of problems are not uncommon and are clearly exposed with WFMU.

Conditional Logic

As you can see from the above example, we can easily capture conditional logic by using nested bullets and conditional statements eg:

10. Editor writes decision

    1. If accept → publish (go to 15)

    2. If revise → Author revises, return to (5)

Documenting Automation

Automation can also be described using WFMU, for exam

1. Author Submits

2. System checks document validity

   1. If all passes -> create workspace

   2. If fail -> generate report for Author

Note: When designing new or optimised workflows that involve automation, we must avoid magical thinking. To this end, it is good to have trusted technicians in the room to help the group understand the promise of technology.

A Workflow Sprint is a fast and efficient methodology for organisations to understand and optimise their publishing workflows before making technology choices.

This process was designed after observing some common mistakes:

• investing in slow and costly general requirements research

• looking at workflows mainly through a technology lens

Understanding and improving workflows need not be lengthy or expensive. Traditional processes like interviewing staff and producing large narrative reports are slow, expensive and often lack clarity.

In contrast, Workflow Sprints produce clear outputs in days, not months. The Sprint first investigates current workflows and then defines optimised ones. With these results, organisations can make informed technology decisions.

Coko designed this process and we facilitate Workflow Sprints, we are also documenting them here in case you wish to try them yourself.

Principles of Workflow Sprints

There are some fundamental principles of Workflow Sprints:

Principle 1: Invite operational stakeholders

The best people for describing an existing (or speculative) workflow and optimising that workflow are the people actually doing the work now - your team (operational stakeholders).

Principle 2: Group discussion is essential

Group discussion involving the operational stakeholders is the most effective way to understand and optimise workflow. Having these experts in the same room eliminates guesswork and team members can drill down into an issue together in quick time to tease out the fidelity needed.

Principle 3: Facilitation is key

Experienced facilitation conducted by someone external to your organisation is critical for keeping the momentum going and managing any potential and problematic team dynamics.

Principle 4: Keep the documentation light

If the documentation of the workflow is not something decision makers can easily grasp, then you are doing it wrong. Use Workflow MarkUp (WFMU - see documentation) to aid in expediting the documentation process while producing clear, human-readable documents.

Now that we have the principles covered, let’s take a brief look at what a Workflow Sprint actually looks like.

What does a Workflow Sprint look like?

Photos included are from actual Workflow Sprints (arXiv, Open Education Network, Ravenspace, Érudit, Organisation for Human Brain Mapping, Wormbase/Micropublications.org).

A Workflow Sprint is a facilitated, structured conversation between the organisation’s primary stakeholders. The stakeholder group should comprise those people that are part of the current workflow (constituting all parts of the workflow) and decision makers.

Operational stakeholders are the people who do the work. These are the most important people to have involved because they are the ones that understand what is done, on the floor, at this time. Sometimes, if automation is involved, a trusted technician that knows the limits and possibilities of publishing technology might be useful. No Workflow Sprint can occur without operational stakeholders.

Strategic stakeholders are the organisation’s decision makers. The decision makers may, or may not be part of the process, however, they will certainly utilise the outcomes to guide them in making decisions going forward. It can be a good idea to include strategic stakeholders to build internal buy-in.

The Workflow Sprint draws these two types of stakeholders together in a series of remote or realspace sessions. If held in realspace the event can occur over one day. For remote events (which we have found to be more fatiguing), the Sprint should be broken down into multiple shorter sessions over several days.

The facilitator guides the group through a process designed specifically for your organisation. The steps usually include (discussed in more detail below):

1. Introductions

2. High-level description of the goal

3. High-level discussion

4. Documentation of the existing workflow

5. Open discussion

6. Designing an optimal workflow

7. Report (optional)

Each phase of the above process should be fun and characterised by a high level of engagement from the team.

Simple tools such as whiteboards (or ‘virtual whiteboards’ if remote), large sheets of paper, and markers are often used to draw out existing workflow processes or future workflow ideas.

Workflow Sprints are fun, efficient, cost-effective, and fast. The process is a good way to generate additional internal buy-in for a project and to quickly help everyone understand the broader goals and challenges.

We have found that Workflow Sprints are also extremely effective team-building events. If held in realspace, we advocate good food and coffee! If done remotely, we sometimes include some less formal moments to help people relax and get into the flow of the event.

Now let’s look at the process in more detail. The following is not comprehensive, but it should give you a good starting point. If you want to drill down further into the process, feel free to contact me.

Speculative vs extractive Workflow Sprints

Before we get started, a quick word about two types of Workflow Sprints already hinted at throughout this document. The two types are:

Speculative - Speculative Workflow Sprints imagine new workflows. Typically new entrants or start ups require speculative Sprints. Inevitably the speculative variety can reveal a lot of contradictory requirements and ‘blurry vision’ that need to be discussed and examined in detail. Sometimes, the outcomes may also lead to compromises the stakeholders may find difficult to accept. Consequently, Speculative Workflow Sprints often take longer and require a higher degree of expert facilitation.

Extractive - Extractive Workflow Sprints start by examining a known (existing) workflow. Generally speaking, these descriptive processes are easier to facilitate and quicker to document.

Realspace vs Remote

A word regarding remote vs realspace events. In-person Sprint processes are definitely more effective and quicker. Remote Sprints are possible, however, the dynamics and format change somewhat. Documentation for remote events is usually done with shared virtual whiteboards, and the process is usually split into several shorter events spread over a number of days.

Hybrid Workflow Sprints (a mix of virtual and in-person participants) are also possible but are harder still, mainly due to the fact that the tools used for documentation are necessarily different, which makes it harder to share ideas across a team split between real and virtual spaces.

The team

When hosting a Workflow Sprint, the first question you need to answer is - who do I invite? There is a simple rule - invite enough operational stakeholders to have every part of the workflow covered. Having strategic stakeholders may be (not always) a good idea, but do keep in mind the more people involved that don’t do the work ‘on the floor’ the longer the process will take. Having said that, strategic stakeholders stand to learn a lot during the process if they participate.

In the case of ‘speculative’ (new) workflows, you need to gather the people with the vision and some folks that know about the kind of work you have in mind.

The space

If the Sprint is held in realspace, it is good to have a single table that can seat everyone involved. In addition, break-out spaces with enough whiteboards or paper and markers to go around are necessary. Post-it notes are welcome but not required.

Facilitation

It is very important to have a neutral facilitator. The facilitator needs to ask hard, bothersome questions, and consequently it is much easier to do this if the facilitator is not subject to internal power dynamics and existing interpersonal relationships. In addition, the facilitator must:

1. Facilitate conversations - the facilitator must hold the space for the group to come together and share their knowledge and ideas.

2. Manage the process - the facilitator must keep the process moving forward.

3. Balance group dynamics - the facilitator constantly reads the group, pre-empting obstacles to collaboration and productivity and adapting the strategy accordingly.

Facilitation is a deep art and there is way too much to go into here (yet another thesis…). However we strongly advise hiring (us!) an experienced facilitator from outside your organisation.

The steps

As mentioned above, the process generally follows a similar pattern but should be adapted before or during the event if necessary:

Introductions

Quick introductions of everyone in the room.

High-level description of the goal

The facilitator outlines what the group is trying to achieve and, in quick detail, describes the Workflow Sprint process. A strategic stakeholder may be introduced to give a 5-minute validation of why the group is gathered.

High-level discussion

It is always necessary to start with a very high-level discussion about the workflow and what the group is trying to achieve together. In general, the Workflow Sprint process starts with a very wide (sometimes meandering) conversation and very quickly begins to focus on specifics.

Documentation of the existing workflow

If the group is large, the facilitator may break it down into smaller groups to drill down into specific parts of the workflow. Each group will then present their documentation back to the larger group. At the completion of this process, workflow should be documented in its entirety in front of the entire group (using whiteboards or large pieces of paper or shared virtual whiteboards if working remotely). Documenting with everyone present helps validate the workflow and ensures any vagueness or ‘gotchas’ are caught.

Open Discussion

A general discussion on what people think about the existing workflow. It is good to allow this to slip into a little brainstorming in anticipation of the next step.

Designing an optimal workflow

The facilitator generally breaks the team into smaller groups. Each group chooses some part of the workflow (or the entire workflow) they wish to re-imagine. Documentation is often captured with drawings (there is no preferred format - let each group decide). Each smaller group’s work is presented back to the entire group and discussed. From this, the facilitator can document (also in front of the entire team) a proposed optimised workflow.

Report

Generally, the facilitator will take all the documentation and distill it into a short report. Documentation of the outcomes usually uses workflow notation (see below) as well as pictures of all the artifacts created during the event. The facilitator generally adds further information to tease out some questions for the organisation to consider (contradictions/compromises etc).

What are the outcomes of a Workflow Sprint?

There are two direct outcomes of a Workflow Sprint:

1. Documentation of the existing workflow - a description of your workflow as it exists now.

2. Documentation of the optimised workflow - a description of the ideal, optimised, workflow.

In addition, depending on how much your facilitator understands about publishing, they may wish to generate a third outcome: a report - a report with the above two items plus narrative about the realities of achieving the optimised workflow and any other issues that may need to be considered.

From this report, the organisation should be in a very good position to consider technology options. A publisher can now do a gap analysis to evaluate existing solutions or start the design process to build new technology.

Kotahi provides extensive versatility to model diverse workflows through its configurable roles, forms, tasks, and review systems. However, fully customizing a complex platform can seem daunting. Here is guidance on rolling out Kotahi incrementally by blending workflow design concepts with lean development principles:

Start by Focusing on One Usecase

Don't try to "boil the ocean" upfront. Focus your initial implementation on the primary or easiest use case. Get one core workflow fully operational before expanding scope.

Focus on Workflow First

Start by modeling your first optimal use case (as above) and workflow, independent of technology constraints. Use techniques like workflow mapping and sprints. Define key roles, content flows, and bottlenecks to address.

Deploy in Small Batches

Map the conceptual workflow to Kotahi in stages, starting with a minimal viable product. For example, first focus on getting base submission and review forms operational.

Gather User Feedback

After each incremental deployment, solicit user feedback through direct discussion. Identify pain points and opportunities.

Continuously Improve

Utilize feedback to rapidly iterate improvements aligned with the workflow vision. Add features, enhance forms, modify configurations etc. in small batches.

Foster Collaboration

Facilitate open communication with your users throughout the process. If possible, form a cross-functional team empowered to collaboratively guide the rollout.

By blending workflow design with lean, collaborative development practices, Kotahi can be implemented iteratively at a sustainable pace. The focus is on incrementally enhancing real-world operations through participatory prototyping and user-centered improvement. With this adaptive approach, the full benefits of Kotahi’s versatility can be realized over time.

☐ Plan your workflows - Map out your team's current or ideal workflows. Identify key roles, content types, review models, etc (can be done without a running instance of Kotahi).

☐ Develop content model - Plan how manuscripts, data, and metadata will be structured (can be done without a running instance of Kotahi).

☐ Install Kotahi - Get a Kotahi instance running yourself or pay a service provider to do it.

☐ Brand Kotahi - Customize the look, feel from the System Settings.

☐ Configure system settings - Set up core parameters like notifications, crossref integrations etc.

☐ Build submission forms - Construct customized forms to capture metadata from authors.

☐ Design review forms - Create tailored forms to collect feedback from reviewers.

☐ Model tasks - Configure task templates to define workflow steps.

☐ Customise PDF - Configure PDF to your inhouse designed (if required).

☐ Customise CMS - Customise the Kotahi CMS or integrate with an external CMS.

☐ Invite intital users - Onboard team members by sending invitation emails to create accounts.

☐ Run tests - Validate workflows, forms, and integrations function as intended.

☐ Go live - Flip the switch to activate for real-world usage!

☐ Gather feedback - Continuously collect user feedback to drive improvements.

☐ Iterate and optimize - Use feedback to rapidly iterate and enhance workflows over time.

Kotahi is an open source publishing platform built using modern JavaScript technologies.

Code, issues, and project management

• Codebase: https://gitlab.coko.foundation/kotahi/kotahi

• Issues: https://gitlab.coko.foundation/kotahi/kotahi/-/issues

• Roadmap: https://gitlab.coko.foundation/kotahi/kotahi/-/milestones

• Project Boards: https://gitlab.coko.foundation/kotahi/kotahi/-/boards/317

Installation and documentation

• Install guide: https://gitlab.coko.foundation/kotahi/kotahi/-/blob/main/README.md

• License: MIT

• Docker-based deployment

Technology stack

• Node.js

• React

• Express.js

• GraphQL

• Postgres database

Integrated microservices

• XSweet: Microsoft Word conversion

• Anystyle: Citation parsing

• Paged.js: PDF generation

Additional Coko Ccomponents

• Wax editor: Used in forms, the CMS, the production editor, the manuscript editor

• FLAX CMS: For public-facing pages

Support

For technical support, join our Mattermost channel: https://mattermost.coko.foundation

Publishing is stuck. Legacy organisations are wedded to outdated models, employing rigid processes on antiquated software. This yields expensive, sluggish, and wasteful systems that are stunting better ways of sharing knowledge. Dominant structures and inflexible conventions have stalled attempts to improve publishing, as core power centres remain entrenched and change stays superficial.

But while the current implementation is broken, there is value in what publishing is trying to achieve - to create, refine, and share knowledge. We must reconnect to this core purpose and revisit how we achieve it.

The path forward starts with re-envisioning publishing from its foundations.

At Coko, our focus is on developing the fundamental building blocks enabling publishing to be reimagined in this way. We are constructing core open infrastructure, tools and platforms - aligned with publishing's true purpose of advancing collective knowledge. With this open infrastructure in place, pioneering new publishing models become possible.

From this position of collective power, we envision a boundless future for publishing, where bold new models emerge through open collaboration. A future transformed by radical openness, where minds connect across organisations to co-create, innovate, and progress together.

In this open ecosystem, cross-functional teams seamlessly collaborate—powered by needs and human-centric technologies, not legacy conventions and obsolete systems. The boundaries between creators and publishers dissolve, as they merge together in the service of knowledge creation—not antiquated organisational structures.

Through open collaboration, knowledge becomes more accessible, more representative, more meaningful. Timelines accelerate, costs plummet, and errors disappear as capabilities expand continuously.

Guided by our core values of trust, openness and collective empowerment, we must reimagine publishing from the ground up together. Our shared responsibility is to pioneer these new workflows, technologies, and models that unlock publishing's immense collaborative potential.

Not simply improving publishing, but redefining it.

This is publishing's collaborative future. This is Coko’s journey.

We advocate for the adoption of open web formats throughout the publishing workflow. Open web formats (eg, HTML, JSON, CSV) should be embraced as core publishing formats. They enable publishing on the world's largest collaborative platform - the web.

• Enable multi-modal content

• Enable real-time collaboration

• Proliferation of format conversion options

• Support progressive structuring

• Enable single source publishing

We advocate for Single Source systems. By using one content source across authoring and production, Single Source systems enable seamless collaboration, reduce handoffs, eliminate conversions, condense timelines, and connect workflows.

• Use open web formats throughout the process

• Connect content creation and production

• Enable concurrent workflows

• Allows real-time collaboration

• Reduce handoffs between teams

• Lower costs by eliminating conversions

• Condense overall timelines

• Promote synchronous operations

• Reduce errors by minimising versions

• Adapt to future needs

Publishing has become unnecessarily complex. The current fragmented systems result in disconnected teams, wasted effort, and preventable errors.

Publishing is a process, not an organisation. Publishing should focus on needs, not be constrained by existing organisational structures.

The boundaries between authors and publishers must dissolve. We must move past artificially separated systems and embrace collaborative creation and dissemination.

New, open processes require new, Open Source technologies. To reimagine publishing, innovative workflows require empowering new technologies.

Collaboration, concurrency, and communication are essential. By integrating real-time teamwork into systems, we can break down silos, work in parallel, condense timelines, and reduce costs.

Deep collaboration changes everything. Deepening collaboration transforms structures, flattening hierarchies, decentralising leadership, and shifting to collective ownership and integrated teamwork.

Publishers must embrace facilitative leadership. Facilitation unlocks collective potential as dominance gives way to inclusion, silos are replaced by openness, and individual agendas dissolve into shared purpose. The end result is empowered teams, accelerated workflows, and publishing that truly serves its community.

Systems should be designed with open, cross-functional spaces. Cross-functional digital spaces allow teams to collaborate without boundaries. Hardcoded workflows construct gated paths that inhibit emergent teamwork.

Open source tools reduce the barrier to entry for innovators. Open source software, when developed professionally, can provide high quality, innovative, systems at lower costs by sharing efforts across organisations.

Kotahi
https://kotahi.community

Coko
https://coko.foundation

Kotahi Support
https://mattermost.coko.foundation

Kotahi Code
https://gitlab.coko.foundation/kotahi/kotahi

Wax
https://waxjs.net

XSweet
https://xsweet.org

Paged.js
https://pagedjs.org

Contact
Adam Hyde (Coko Founder): adam@coko.foundation

AnyStyle - An open source citation parsing tool that identifies reference strings and matches them to citation metadata. Developed by Coko.

API - Application Programming Interface. Enables software to exchange data and interact with Kotahi programmatically.

Archetype - A predefined configuration or template for workflows and publishing models in Kotahi.

Automatic ingestion - The automated importing of content into a system. Kotahi can be configured to automatically ingest manuscripts from sources like preprint servers.

arXiv - A popular preprint repository used across many scientific disciplines.

bioRxiv - A preprint repository for biology, operated by Cold Spring Harbor Laboratory.

Collaborative review - Multiple reviewers work together, either openly or anonymously, to provide a consolidated set of feedback.

Community review - Self-organisation of reviewers from the community, often used for post-publication review of preprints.

Coko - A non-profit building open source publishing infrastructure to enable new models of research communication.

Cokoserver - An open source workflow server by Coko that integrates tools and manages publishing operations.

Containers - A standardised unit of software encapsulating code and dependencies. Kotahi uses Docker containers.

Concurrency - The execution of multiple tasks or processes at the same time. In publishing, it refers to authors, editors, designers, etc. working on a project simultaneously.

Crossref - A nonprofit collaborative reference linking service that provides persistent identifiers (DOIs) for scholarly research.

Curation - the process of selecting, organising, and presenting content to enhance its value, context, and accessibility for specific audiences.

Deployment - The process of installing, configuring, and running an application like Kotahi on servers to make it available for use.

Docker - An open platform for developing, shipping, and running applications using containers. Used to package and deploy Kotahi's microservices.

DOI (Digital Object Identifier) - A unique persistent identifier for digital objects like journal articles. Provided by identification systems like Crossref.

Downconversion - Converting a structured document format to a less structured one, usually involving some loss of information. E.g. HTML to plain text.

Double-blind review - The identities of both authors and reviewers are concealed from each other throughout the review process.

Evaluation - The process of assessing a manuscript or preprint submission through peer review and editorial decision-making.

Express.js - A lightweight Node.js web application framework used in Kotahi for routing, middleware, and APIs.

FLAX - An open source static site generator and publishing framework developed by Coko, built on 11ty. FLAX is integrated into Kotahi.

Form builder - A tool for creating customised forms to collect submission metadata in Kotahi. Enables optimising submission workflows.

Fragmented Publishing Process (FPP) - A disjointed publishing process involving different teams, tools, and file formats between the content creation and production stages.

Git - A distributed version control system for tracking code changes. Kotahi uses GitLab for repository management.

Group - In Kotahi, an isolated publishing community like a journal, preprint server, or review collection. Groups act as independent tenants.

Instance - A single installed copy of the Kotahi software. Can contain multiple groups running independently.

JATS (Journal Article Tag Suite) - An XML-based standard format for structuring and encoding scholarly journal articles to enable archiving, exchange, and preservation.

JavaScript - A programming language commonly used for web development. Kotahi is built primarily using JavaScript technologies.

Manuscript - A written document containing research findings submitted for publication in a journal.

Metadata - Data about a publication, like title, authors, keywords. Required for identification, discovery, and management.

Micropublication - Bite-sized scholarly outputs focused on a single finding or idea, enabled by web-based publishing.

Microservices - An architectural approach in which an application is composed of small independent services that work together. Kotahi employs a microservices architecture.

Multitenancy - An architecture where a single software instance serves multiple independent groups like journals or preprint communities.

Node.js - An open source JavaScript runtime environment for building server-side applications. Kotahi's backend services are built using Node.js.

Notifications - Emails, in-app messages, and alerts to notify users of events and updates.

Open review - Reviewers and authors are known to each other during the review process. Reviews may be published alongside articles.

Open Source - Software with source code that anyone can inspect, modify, and enhance.

Paged.js - An open source JavaScript library for pagination and print-quality PDF generation from HTML. Developed by Coko.

Paged Media - An evolving CSS standard for styling and laying out content in paged environments like PDF documents. Enables print-quality typesetting from HTML.

Postgres - An open source relational database system used by Kotahi to store content and metadata.

Preprint - A manuscript that is shared publicly prior to formal peer review and publication in a journal.

Preprint servers - Online repositories for sharing preprint manuscripts, like arXiv, bioRxiv.

Preprint review - the process of assessing and evaluating scientific preprint articles (usually) prior to formal publication in a journal.

Production tools - Components of a publishing system that prepare content for final publication, like typesetting and PDF generation.

Progressive structuring - The ability to incrementally add more structure to a document format without interrupting the workflow.

Publish-Review-Curate (PRC) - An emerging publishing model based on posting preprints, community peer review, and curation.

Real-time editing - A feature allowing multiple users to collaboratively edit a document at the same time and see live updates, such as in in Google Docs.

React - An open source JavaScript library for building user interfaces. Used extensively in Kotahi for UI components.

Research object - A generalised term in Kotahi referring to any submitted item, including articles, data, code, presentations etc.

Review rounds - Iterative stages of peer review in which a submission may go through multiple cycles of assessment, revision, and re-review. After each round, the editor makes a decision to accept, reject, or initiate another review cycle.

Rolling submissions - Authors can update submissions during an active review round if enabled (this has proven useful for some preprint review use cases).

PID (Persistent Identifier) - a long-lasting reference to a digital resource that does not change over time. PIDs like DOIs allow reliably locating content even if it moves or changes hosts. Using PIDs enables consistent access and integrity in linking between related research objects across systems.

Scalability - Ability of a system to handle increased usage and data volume. Kotahi scales using microservices and containers.

Sciety - A platform built by eLife to aggregate preprint peer reviews happening across the web and power PRC workflows.

Single-blind review - Reviewers know the author's identity but authors do not know the reviewer identities.

Single Source Publishing (SSP) - Utilising a single file format throughout both content creation and production stages of publishing.

Structured text - A simple markup language like Markdown or AsciiDoc that adds some basic structure for formatting documents.

Submission - The process of submitting an article or other research object for publication or review in Kotahi.

Taxonomy - A hierarchical system for categorising and organising knowledge.

Tenant - An independent group within a shared Kotahi instance, like a journal or preprint server community. Multi-tenancy allows supporting many groups on one platform.

Typesetting - Adapting content styling and layout for different mediums like print or mobile screens.

Upconversion - Adding structural information to enhance a document's fidelity, like HTML to XML.

Versioning - Tracking revisions to submissions by creating new iterations or ‘versions’ recording the changes.

Wax - An open source browser-based rich text editor for scholarly writing and publishing, developed by Coko.

Workflow - The end-to-end set of tasks, roles, and steps involved in a publishing process.

XML-first - A single source publishing approach involving all users working directly in XML files and tools.

XSLT - A language for transforming XML documents into other formats like HTML. USed in XSweet.

XSweet - An open source tool by Coko for converting Microsoft Word documents to HTML.

In the world of publishing, content creation and production are often disconnected processes. Content creation happens in isolation from the production phases, and the technical systems and file formats used in each stage are often completely separate.

Single Source Publishing (SSP) utilises a single source file throughout the content creation and production phases.

Fragmented Publishing Processes

In numerous publishing environments, authors, copy editors, and proofreaders use a single tool, often Microsoft Word, to create and refine content. This content then undergoes production, where it is converted into various formats such as Web, HTML, PDF, XML, and ebook formats, either programmatically using software or manually by individuals using applications like InDesign.

This separation between content creation and production creates a disconnect in the people, tools, and working files involved in the process. A simple example to illustrate the issue is when content changes are required after it has entered the production stage. This necessitates a multi-step process involving communication between content creators and production staff, using their respective tools, and then checking the changes made. This back-and-forth process can be not only time-consuming and expensive but also involve numerous conversions, leading to multiple versions and potentially introducing errors along the way.

We could call this type of process a Fragmented Publishing Process (FPP). This term emphasises the disjointed nature of the process, as it requires ‘jumping a gap’ between different teams, tools, and formats from the content creation to the production stages.

Single Source Publishing

Single Source Publishing (SSP) tackles the main challenge of FPP by enabling both content creation and production stages to utilise the same file format. While shifts in teams and tools may still occur during each stage, SSP ensures that both stages remain linked through a shared ‘single source’, promoting smoother transitions between them.

In a Single Source Environment, for instance, when content alterations are needed during the production phase, the content creation team can make those modifications using the same source file utilised by the production team. This ensures smooth integration into the production process, as both teams are working on the exact same files.

SSP seeks to simplify the publishing process, leading to considerable time and cost efficiencies. There is also a reduced likelihood of introducing new errors, as SSP eliminates the need for multiple conversions and manual interventions between content creation and production stages.

Concurrency - the real benefit of SSP

However, the advantages of single source publishing (SSP) extend beyond merely facilitating a smoother document exchange between content creators and production teams. In an SSP environment, the real value lies in concurrent workflows.

Concurrency, in general terms, refers to the execution of multiple tasks or processes at the same time. In the context of publishing workflows, it is the ability for authors, editors, illustrators, and designers to all work on the project at the same time. For example, while an author is in the process of writing the main content, an illustrator could be designing illustrations or graphics and placing them in the text. Simultaneously, a copy editor might be reviewing and editing completed sections of the text, and a designer could be working on the layout and formatting of the book or digital publication.

There are two primary advantages of concurrency:

1. Condensed product completion time: Concurrent workflows allow tasks to be completed in parallel, speeding up the overall process.

2. Enhanced collaboration: Concurrent workflows cultivate a collaborative environment with real-time interaction, fostering open communication and faster decision-making by addressing questions and feedback promptly.

Concurrency, stemming from a well-crafted SSP system, is vital in elevating the efficiency of publishing workflows. It could be argued that concurrency represents the true value of SSP.

Concurrency and realtime-editing

It's essential to highlight that one crucial feature must be present for concurrency to truly reach its full potential in terms of efficiency: real-time editing. Real-time editing allows multiple people to edit a document simultaneously and see each other's changes in real-time, similar to tools like Google Docs or design applications such as Plasmic and Figma.

To achieve genuinely concurrent workflows, real-time editing must be enabled, allowing all team members to modify the file and perform their tasks at the same time. Without this feature, we would need to rely on locking files while one team member works on them, which may be preferable in certain situations (for example, a copy editor may not want an author to add new content to the same chapter they are editing). However, in most cases, real-time editing significantly enhances the benefits of concurrency.

Simple SSP

The simplest, and most common, way to implement SSP is to require that everyone involved in the publishing process use the same tools. Since production tools can modify content but authoring tools (e.g., MS Word) generally cannot adjust layout, style, or design elements, content creators are often required to use production tools. Some effort has been made to improve these tools for content creators, but the strategy has limited success.

We'll start by exploring this strategy in a common scenario – using an ‘XML-first’ environment in which all parties involved in the publishing process work directly with XML files and tools more commonly used by production staff - XML editors. As highlighted in Peter Meyer's insightful 2004 presentation on SSP, this approach offers both benefits and challenges that we'll discuss in more detail.

Meyer presents many arguments in favor of designing SSP systems around XML, but chief amongst them are its adaptability and longevity. In situations where documents are held and updated over long periods, employing XML can help avoid technological obsolescence of the content caused by changing software versions and publishing styles. This ability to stand the test of time and adapt to various requirements make XML a common and celebrated choice for publishing systems. Meyer, amongst many others, believes that XML serves as an excellent file format for Single Source Publishing.

This strategy can be successful for a known group of regular authors; however, Meyer points out several challenges. One notable challenge is the need for authors to possess a thorough understanding of the specific rules governing a document's structure, known as the ‘schema,’ as well as the capability to edit XML. Meyer observed that within any group, about a quarter of authors could edit XML and work with a moderately complex schema without extensive training and support. Half of the group might learn to use the application with varying efficiency, while the remaining quarter would likely struggle to adapt to the new content authoring process.

One way to address this issue is to develop an editor that feels like a word processor but edits structured XML ‘under the hood.’ This, however, is challenging. Developing an interface that is intuitive, flexible, and preserves the structural integrity of the highly structured and rigid XML document is difficult and expensive. Additionally, updating the interface to accommodate changes to the overall document structure (schema) can be a complex and costly process.

It's important to keep in mind that even with the most user-friendly interface for editing XML, authors are still required to understand the document structure, use it correctly, and learn a new tool. These factors can contribute to challenges in adoption and productivity when implementing Single Source Publishing with an XML-first approach.

Essentially, when dealing with XML, it becomes clear that expecting authors and content creators to use tools that require them to add any kind of structure beyond the basic "display structure" (the visual organisation of content as it appears in a typical word processor) is not particularly effective.

There have been other attempts to solve for the problem of unfriendly author experience when using highly structured document formats. Some platforms, like Overleaf for example, have attempted to simplify the author experience by combining user-friendly, word processor-like tools, with LaTeX markup. This takes away some of the disruptions to the writing/content production flow, however, it still requires content creators to learn and conform to the structure and markup of LaTeX and faces the same adoption and productivity issues. However this strategy has proven effective for those wishing to learn LaTeX, which is mainly researchers in 'hard sciences'.

There are still other approaches to requiring everyone to use tools more commonly used by production staff. A few publishers have required authors to use desktop publishing systems like InDesign. The idea being that they write in InDesign (or similar) and then the designers can also work in the same environment. Thankfully, this approach is uncommon, as it also disrupts the natural writing process for authors more familiar with word processing software like Microsoft Word or Google Docs.

The examples provided are not exhaustive, but they effectively demonstrate the challenges encountered when expecting all users to adopt tools typically used by production staff. Although it may be somewhat successful, this approach can lead to issues with adoption, a higher likelihood of introducing errors (particularly in terms of structure), and often results in productivity loss. Additionally, it necessitates considerable resources for training and support.

Simple File Formats

As mentioned earlier, highly structured file formats can present challenges. Can a simpler file format be the solution? Some SSP systems attempt to address this issue by using simpler file formats like Markdown and AsciiDoc. I have previously discussed the benefits and limitations of this approach in detail. The primary drawbacks are the lack of advanced formatting options, the necessity for content producers to learn a new, somewhat technical syntax, and the difficulty in adding the required structural information for styling and layout of published content, even though these formats are known as, paradoxically, 'structured text' formats.There is a use case for Markdown and AsciiDoc in SSP, but it ls largely for content creators who are also technical eg technical documentation (although there have been some production companies, such as Electric Bookworks, that have taken Markdown workflows quite far into other categories).

Qualities of a SSP File Format

How can we solve the 'SSP problem' when both complex and simple file formats fall short? What, then, are the characteristics of a good SSP file format?

An ideal file format for a single source publishing system must have certain qualities to meet the needs of both content creators and production staff. First, as we have already established, it should be compatible with tools that are familiar to both content creation and production teams.

Secondly, it is important to consider the distinct objectives of each group working with the file. Content creators focus on adding content, while production staff primarily concentrate on structure to enable conversion to other formats and display environments (discussed in more detail below). Essentially, the file format must be capable of containing minimal, moderate, or extensive structure as it passes continuously through the hands of both content creation and production staff. In other words, the file format should support progressive structuring without disrupting the workflow.

The argument for HTML

Interestingly, HTML emerges as a strong candidate for an SSP format due to its flexibility in handling document structure and the wide array of content creation and production tools available for working with HTML.

In terms of structure, unlike other formats that enforce strict structure, HTML is capable of accommodating unstructured, partially structured, or fully structured documents with ease. While some may perceive this lack of enforced structure as a drawback or weakness, I believe it is actually one of HTML's key strengths. Moreover, HTML's structural flexibility enables it to accommodate progressive structuring throughout the publishing process, a characteristic critical to well design SSP systems.

The question then arises, can HTML be used to support the 'native tooling' of both content creators and production staff? For content creators, the answer is a resounding yes, as many online word processors that support HTML as an underlying format look, feel, and operate like traditional word processors.

HTML can be effectively employed for production purposes, including converting to XML, creating visually appealing print-ready PDFs, EPUBs, and other formats. The ability to transform into various formats, especially XML and high-quality PDFs, may prompt some inquiries. How exactly is this achieved, and what tools are necessary?

To address these questions, we must explore the requirements for converting HTML to other formats in greater detail. This examination will offer a better understanding of the essential tools and their impact on the culture of production in the publishing industry.

How does HTML get to other formats?

There are essentially three types of document conversion: Upconversion, Downconversion, and Typesetting.

Downconversion

Downconversion entails converting a structured format to a less structured one, such as transforming HTML to plain text. This process involves losing information rather than adding it. Downconversion is straightforward.

Upconversion

Upconversion involves enhancing a document's structural fidelity. This process requires someone or something to add structural information to the document.

As previously discussed, one can add as much structure to HTML as needed. This is accomplished technically by incorporating attributes to the elements and enclosing items with different identifiers. Upconversion is facilitated by mapping these identifiers to other document structures, enabling the automatic conversion of the single-source file format to the structure of the desired target format (e.g., XML).

Typesetting

Typesetting is the process of adapting content to fit specific layouts (and look visually appealing), such as mobile displays or paginated PDFs for print.

Typesetting within an HTML context is a fascinating topic in publishing. There are two primary use cases: HTML display environments (such as laptop browsers or mobile phones) and PDFs for screen display or print. As previously mentioned, CSS is the design language that determines the style and layout of HTML in browsers and phones. Interestingly, CSS has been expanded to encompass rules governing design and layout in page environments, making it a popular method for generating PDFs from HTML. CSS PagedMedia, an evolving standard, is commonly used to create visually appealing, print-ready works from HTML, including all the features expected in print layouts, such as page numbers, margin control, running headers, and orphan control etc.

HTML and CSS are currently being employed to create PDFs for publishers across a diverse range of use cases, including books (as per above) and journals.

In summary, it is possible to achieve all the required formats through the combination of these three strategies, along with the numerous conversion tools readily accessible for converting HTML. In fact, one could argue that the variety of strategies and tools for format conversion is greater for HTML than for any other available format.

The tools

As previously mentioned, it is crucial to identify tools that cater to the needs and working styles of both content creators and production staff. The ideal tools should work with HTML and, optimally, support real-time concurrent operations. Fortunately, such tools do exist, and if they don't perfectly meet your specific use case, they can be cost-effectively extended or custom-built.

Numerous modern word processors that use HTML as their underlying document structure offer a range of benefits, including the ability to support real-time editing. These web-based word processors can be tailored to accommodate production teams, allowing them to mark up more complex structures.

Downconversion is easily supported by numerous conversion tools like Pandoc, making the tooling for this aspect simple. However, the two high-value transformations to consider are upconversion and typesetting.

Typesetting can be accomplished with a relatively simple setup. For example, the book production system PressBooks utilises WordPress and PagedMedia typesetting (employing the proprietary PrinceXML). To add structural information in a PressBooks book, users can take advantage of the customised editor to include the necessary structural information for typesetting.

Similarly, Ketida employs the web-based word processor Wax and integrates with open source Paged.js for its typesetting needs.

Design is managed in both systems by linking the structure with CSS styles. This can be done by editing CSS files using a range of CSS editors popular in web design workflows or by using the built-in CSS template editors available in both platforms.

In yet other strategies, there has been work put into a InDesign-like interface. Hederis, for example, follows this paradigm. The underlying technology behind Hederis is HTML and CSS (and Paged.js for HTML pagination).

If publishers do not have in-house CSS PagedMedia skills, this work can be outsourced to a growing number of design professionals.

Upconversion solutions for transforming from HTML to highly structured formats are available, but they are not extensively distributed or widely adopted. Kotahi is a prime example, providing a word processor interface with controls for marking up display document elements with additional structural information. During export, this information is mapped to the Journal Article Tag Suite (JATS) format and validated, resulting in a clean, well-formatted JATS representation of the article.

MetaData

The observant reader may ask, "What about metadata?" Preparing files in production isn't solely about the structure of the underlying content; it also involves including additional information about the content that isn't considered ‘display content.’ For instance, the ISBN number is not typically part of the content since we don't usually expect to see it within the text of a book. Placing an ISBN at the beginning of a chapter just to ‘carry that information forward’ would be a rather cumbersome solution. However the ISBN number might need to be embedded in some outputs (eg. XML). In journal publishing, particularly, a significant amount of metadata needs to be merged with content into an XML file (JATS) for archiving and distribution.

So, how does this fit into the overall picture? The answer lies in combining content from an HTML file with metadata at export time (when creating JATS for example) and constructing the XML from the individual components. There is no need for metadata like this to live in the original single source file. It can exist anywhere that is accessible to the export mechanism when generating the desired format.

Conclusion

Single Source Publishing is an effective strategy for accelerating publishing workflows and lowering costs. The secret to achieving SSP lies in the nature of a shared file format across content creation and production. Highly structured formats can be problematic, while formats with reduced structure have limited use cases. An effective SSP file format must:

1. Be compatible with tools that are familiar to both content creation and production teams.

2. Support progressive structuring without interrupting the workflow.

HTML emerges as the best contender, as it can accommodate both content creation and production tools, and supports progressive structuring. Although a growing number of tools support this approach, they remain largely under-explored by those who stand to benefit the most from them.

Publish-Review-Curate (PRC) represents an emerging model of research communication combining preprint posting, community peer review, and curation.

The stages of PRC are:

Publish - Researchers first publish preprints openly on servers like arXiv and bioRxiv for early sharing of findings.

Review - Volunteer communities then conduct peer review of preprints in a transparent, public process.

Curate - Preprints undergo a final curation stage for further validation, improved formatting, and communication of findings.

This sequence flips the traditional journal path of Review → Curate → Publish to:

Publish → Review → Curate

Some key aspects of PRC:

• Accelerates research dissemination via preprints prior to formal peer review. Enables rapid sharing of findings.

• Community peer review of preprints in a publicly visible manner amplifies transparency.

• Curation stage improves preprint formatting, legibility of findings, and provides aggregation around topics.

• Curators can be traditional journals but also communities and new forms of curatorial organisations.

• Blends rapid sharing of preprints with improved communication after review/curation.

• Combines benefits of preprints, community review, and curation.

PRC balances accelerating discoveries through preprints with the improved clarity and validation of findings in curated versions. It also maintains focus on preprints as the core, shared object flowing through the processes.

The PRC model represents an evolution of research communication - leveraging preprints to accelerate sharing while retaining the value-add of peer review and curation.

Importantly, PRC is not just a theoretical model but an approach already being adopted by scholarly communities across disciplines.