SFU Sprint Report #1: Documentation

May 29th, 2019 by  | Comments Off on SFU Sprint Report #1: Documentation

Our first report from the SFU Sprint May 6-7, 2019 covers three topics, all related to OJS documentation: email templates, plugins, and upgrading. As an affiliated event with the Library Publishing Forum, we welcomed a large number of library professionals to the table, many seeking to work on non-technical projects. Documentation was by far one of the most popular.

Why Documentation?

For some, documentation means the “how to install” files that come with software. At PKP, we acknowledge the support needs of a much wider user group – one that includes journal managers, editors, and publishers, as well as software administrators. As such, our Documentation Hub (aka Docs Hub) contains user guides, developer documentation, and publishing tips related to our software – much more than just installation instructions. This work is supported by PKP’s Documentation Interest Group (DIG) who host a bi-weekly virtual documentation sprint. The SFU Sprint provided an opportunity to welcome new contributors and collaborate further on three community identified documentation topics.

Topic 1: Email Templates

Need to send an email in OJS 3? Want to notify users of a new issue? Or let the Section Editor know that layout is complete? OJS has a whopping 61 email templates as part of its workflow. Most of these refer to a specific section (e.g., registration, submission, review, etc.) and can be customized. If you’re not sure what each is for, you can click on its name in the email template list (Settings –> Workflow –> Emails), but you can’t see details at a glance and some information is missing. Our sprinters identified these issues and agreed that the current presentation was overwhelming. To solve, they proposed additions to the existing OJS documentation that a) clarify the purpose, sender, and receiver of the email templates and b) further describe where each appears in the workflow. They created a table outlining all 61 email templates and described the sender, recipient, description, and stage of workflow for each. In the process, a few inactive templates were also identified, enabling simplification. This important descriptive work has since been added to Chapter 7: Workflow Settings –> Emails in Learning OJS 3.

Learning OJS 3 — Chapter 7: Workflow Settings — Emails

Topic 2: Plugins

Plugins are heavily used and often essential to extend the functionality of OJS. They are also a great way for community developers to contribute a new feature to OJS. With this popularity in mind, our sprinters raised two concerns regarding existing plugin documentation. First, documentation is scattered across multiple locations (notably Readme files, Learning OJS 3, and the Administrator Guide), making it difficult to access. And secondly, the amount of necessary configuration varies greatly between plugins, thus different types of plugins need different kinds of documentation. As a solution, the group created an inventory of OJS 3 plugins with links to existing documentation and notes regarding further documentation needed and where documentation should be accessed. Our DIG will use this work to create new documentation, enhance existing content, and make it easier to find plugin documentation.

Topic 3: Upgrading from OJS 2 to OJS 3

This last topic is an important one for many OJS users. While we’re proud of all that is OJS 3, we recognize that for some, making the switch after years of OJS 2 usage and customization can be difficult. For those needing support, there are a number of documents and resources available, but they are dispersed. Our sprinters proposed creating a single guide that aggregates and references existing information. This documentation would provide simple guidance on planning and implementing an upgrade and migrating content to OJS 3.x, including decision-making, major differences between the versions, planning, communication, troubleshooting, and post-upgrade steps. By the end of the sprint the group had completed an outline for new documentation. The DIG will finish writing and editing the guide during a future sprint with the goal of publishing it in the Docs Hub.

Thank You

While there’s still work to come, we cannot thank our sprinters enough for both identifying and undergoing the necessary groundwork to realize these improvements. The collaboration of our staff and users working together is what makes our documentation unique – we don’t assume we know everything users need to know, and we grow and improve our documentation based on their invaluable feedback.

Group Members: Amanda Stevens (PKP), Olga Perkovic (McMaster University), Emma Molls (University of Minnesota), Patricia Mangahis (Simon Fraser University/PKP), Kate Shuttleworth (Simon Fraser University/PKP), Andrea Pritt (Penn State University/PKP), Suzanne Jay (University of British Columbia), Vanessa Gabler (University of Pittsburgh), and Kevin Hawkins (University of North Texas).

Want to help make PKP software documentation better, together? Documentation sprints run virtually all year. Check our Documentation Interest Group to learn more.

Tags: ,

Comments are closed.