The first sprint summary from the PKP Minnesota Sprint, hosted by the University of Minnesota Libraries in May 2024, is now available.
Sprints involve PKP community members joining diverse groups to work on PKP software and support. The University of Minnesota Libraries hosted six working groups at the PKP Minnesota Sprint in May. This is a summary of one such group’s work.
In-app Help and Learning OJS 3 Re-haul Thoughts
Documentation is one of the primary ways that Open Journal Systems (OJS) users, including researchers and editors, interact with PKP. User experience with documentation influences their feelings toward the application and generates good will and good practices.
Good documentation also saves time, both for the software users themselves and for the service providers (like library publishers) who are supporting journal managers and editors.
Working Group Members
- Emma Uhl, Public Knowledge Project (PKP)
- Amanda French, Research Organization Registry (ROR)
- Marisa Tutt, PKP
- Marie-Eve Dugas, Érudit / Coalition Publica
- Marianne Reed, University of Kansas
- Tazio Polanco, University of Pittsburgh
- Matthew Vaughn, Indiana University Libraries
Background
Learning OJS 3 is one of PKP’s most used documentation, but feedback from previous exercises (e.g., Library Publishing Forum 2021) has indicated that there is a problem with audience specificity, information density, and lack of “quick” procedural documentation.
The PKP Documentation Interest Group (DIG) has been aspiring to do a significant rehaul with Learning OJS in concert with a future software version release that would address some of these concerns.
Sprint participants identified the following key reasons why they chose to work on this topic, with particular focus on the desire to improve OJS documentation:
- To help to support users better;
- To save time, especially with one on one support;
- To learn from others also writing documentation.
In addition to the goals outlined below, this sprint group wanted to answer and explore questions around quality of documentation: (1) is PKP documentation meeting the needs of our user community? (2) Why do other service providers create their own documentation?
Goals
- To add the hook list that is only in 2.0 technical reference to 3.2, 3.3, 3.4, and 3.5 developer documentation;
- Roundtable discussion about the experience of using Learning OJS 3;
- Aggregation of some thoughts about in-app help;
- Mine inspiration from external documentation for structural and format changes that could be adopted in the Learning OJS re-haul.
Results
- Submitted a pull request to the PKP documentation repository adding warnings to the 2.0 hook list and links to the codebase in 3.3 and 3.4 documentation so that developers know where to find current hooks until a new hook list is published;
- Conversation about in-app help and Learning OJS 3 experience;
- Created a table of external documentation listing some of the most valuable traits;
- Added several new columns to the Learning OJS Copy Editing rubric based on discussion;
- Discussed reasoning for shifting to a more task-based approach, especially for editorial workflow documentation;
- Discussed needs of librarians, e.g., creating their own customized documentation for their contexts;
- Considered the purpose, distinctions, similarities, strategies, and future of both the PKP Education Interest Group (EIG) and the Documentation Interest Group (DIG).
Next Steps
The goal of the sprint is to complete short projects before the end, but often there are leftovers to explore and the results here become the starting point for future work.
- Publish a full hook list using PKP documenter, at which point that should be referenced from the appropriate places in the documentation;
- Figure out a way to deprecate and demote older documentation in Google search results;
- Directly extract highlights from external documentation into plan for copyediting project;
- Further integrate overall feedback and findings into the greater copyediting project;
- Chat with development team about the potential of in-app help;
- Analyze user entry points and journeys (e.g., get deeper into Matomo).
Thank You
We once again thank the Sprint sponsors, host institutions, and all participants for their valuable contributions to the PKP user community. Special thanks to University of Minnesota Libraries, Library Publishing Coalition, and Crossref for their support and partnerships.
