Helsinki 2022 Sprint Notes Released: Documentation

July 19th, 2022 by  | Comments Off on Helsinki 2022 Sprint Notes Released: Documentation

In June 2022, The Federation of Finnish Learned Societies hosted a PKP software sprint in Helsinki, Finland. During this sprint, PKP community members gathered to form several groups, with each group tackling a specific task. This is a summary of one such group’s work.

Group members

Abstract

PKP actively develops and maintains PKP | Docs as a guide for using its publishing software. While the documentation of OJS is extensive, user feedback indicates a need for simplified, procedural guides for role-specific tasks within OJS. The documentation group worked to identify these tasks for author, reviewer, editor, and technical staff roles and to create relevant, step-by-step documentation to serve this goal. Additionally, the group leveraged their multilingual skills to translate instances of existing documentation into French, Finnish, Swedish, Norwegian and German, while providing helpful feedback on the translation tool used by PKP.

Goal

This group’s goal was to expand and improve upon PKP’s existing documentation pieces to support software users.

Day 1

Background

The group came together to discuss their histories with writing and using documentation from PKP and their own sources. Consistent with previous assessments and user stories, we found that many participants were still writing their own OJS documentation to assist with certain tasks. In some cases, this was a way of having simplified documentation in the language of the region, but overall there is a sense that while Learning OJS and other guides are useful, there are times when users are looking for streamlined, procedural documentation.

Additionally, guides like Learning OJS 3 tend to address workflow stages for a broad audience. The group identified some common tasks for specific user groups that would be suited for highly simplified, procedural documentation, and began work on so-called “quick start” guides that would serve as a reference for these common tasks.

Documentation Work

The group first shared some of the documentation they had previously made publicly available in their regional languages, allowing for a better understanding of who is creating documentation outside of PKP, in what languages, and for what purpose.

Additionally, as a result of the group’s efforts, the following “quick start” guides were partially or fully drafted:

  1. Author tasks: (a) fully completing a submission, and (b) making revisions
  2. Reviewer tasks: accessing and performing a review
  3. Editor tasks: guiding a submission from reception to publication (including adding identifiers)
  4. Technical Staff: documentation contribution guidelines for technical staff

The work here will be brought back to PKP’s Documentation Interest Group, who will prepare the guides and find a suitable way to present them in the Docs Hub.

Day 2

Background

Our group expanded on the second day as other groups at the Sprint moved on to development and coding work, and members without technical expertise joined us. On this day we decided to leverage the international setting and the multilingual capabilities of many of the Sprint’s attendees, and we opted to engage in some documentation translation. 

This also essentially served as one of the first live tests with translators available to provide immediate feedback on the (somewhat) newly adopted platform, Crowdin, which also provides PKP’s translation coordinator with invaluable feedback about the ease of use of the tools and its features.

Documentation Work

The following documentation translation projects were started by the group on Crowdin:

  • ORCiD Guide – French
  • Learning OJS 3.3 – Authoring – Finnish
  • Learning OJS – About OJS – Finnish
  • Crossref Plugin Guide – Swedish
  • DOI Plugin Guide –  Norwegian
  • Developer Documentation – Plugin-Guide – German

Additionally, one member worked on original documentation in their regional language (Dutch) of a similar nature to the quick start guides created on Day 1.

Given that translation is a laborious process and that the Sprint was a short event, it is not surprising that no translations were fully completed. However, the group graciously shared their thoughts on the translation platform, expressed interest in promoting translation work to their colleagues, and proved that documentation translation is a great activity for sprints wherein PKP gets the opportunity to talk to individuals in communities that use languages other than English.

Thanks

Our thanks to the Federation of Finnish Learned Societies for hosting the sprint; and to the PKP community, both in attendance at the sprint and elsewhere, for their valuable guidance.

The Helsinki 2022 Contributor Roles sprint group generated the ideas contained in this blog post while the post itself was written by Emma Uhl and edited by Famira Racy and John Willinsky. Credit also goes to everyone in the group including Erik Stattin, Jesper Thestrup, Lena Lönngren, Christoph Otte, John David Didriksen, and Susanna Virtanen.

Below: photo taken in Helsinki by PKP’s own Jason Nugent.

Tags: , , ,

Comments are closed.