PKP 2017 Sprint Report: Documentation Update and Architecture

At the 2017 PKP Sprint, the Documentation Update and Architecture group worked on a prospective Roadmap for Updating PKP Documentation, aiming to solve broader issues related to the organisation, redundancy, and hosting of distributed documentation across all PKP software. Starting with a focus on the way documentation is presented on https://pkp.sfu.ca and also the PKP Wiki, the group made a number of initial recommendations with regards to how to best organise, create, and de-clutter PKP docs.

Members of the group included:

Janna Avon

Alex Garnett

Kevin Hawkins

Mike Nason

Emma Molls

Kevin Stranack

Janet Swatscheno

Team members identified and evaluated resources in the PKP Wiki to determine which docs were redundant or unclearly labelled. This list will be used to weed the PKP Wiki until such a time as all the docs that live there can be safely migrated to a new platform. Additionally, the team created a list of new potential platforms for hosting PKP documentation, including GitBook, which is currently in use. Other platforms under consideration included:

MKDocs

Read the Docs

docsify

Grav Flat CMS

GitHub Pages

and a few others…

These recommendations will be rolled into a specific Documentation Recommendations Document by the coordinator of the Documentation Interest Group and presented to the PKP Technical Committee for consideration moving forward.

Team members also made recommendations with regards to documentation classifications, distinguishing between guides, documents, books, and classes. In this scenario, guides represent smaller documents with specific tasks users might want to accomplish, with short solutions. Documents would be a little longer, and “books” more fully-fledged and comprehensive. “Classes”, in this case, would be specific to the content of PKP School.

The work of the Team Members in this group – from inventory to environmental scans and use-case recommendations – will be instrumental in aiding the untangling of documentation for PKP projects and software.

With the release of OJS 3.0 on the horizon, the documentation group at the 2016 PKP Code Sprint focused on creating a solid foothold for OJS 3.0 documentation for users. The long-standing 2.x documentation for OJS, while tremendously extensive, was not particularly focused around common user tasks. With the 3.0 documentation we decided that the best approach to new documentation would be task-based and represent the chronological progression from journal installation to managing submissions. It would also specifically address asynchronous tasks such as article submission – tasks undertaken by OJS users everyday – in many ways echoing the intent of PKP School resources: setting up a journal, adjusting settings after installation, submitting/reviewing an article, publishing an issue… etc.

Since OJS 3.0 was very new to most members of the documentation group, it was decided that our goal for the sprint would be to begin laying out a basic framework for documentation, pulling in content from OJS 2.x guides where it was relatively obvious that few changes would need to be made. As an additional proof-of-concept for task-based documentation, the group also created a new guide outlining the step-by-step author-submission process.

Team members worked collaboratively using Google Docs and, as docs were created, they were migrated to GitBook. Ultimately, the GitBook format will allow key user documentation to be hosted in GitHub where more fluid, community-based modifications to the documentation can take place. GitBook also allows for users to access the material as a PDF, EPub, MOBI, or HTML page.

The beginnings of the book can be accessed online (https://www.gitbook.com/book/pkp/ojs3/details). While the theme of the sprint always explicitly states, “no homework”, documentation never sleeps. Feel free to follow along over the coming months as we continue to mold the task-based documentation into the user guide for OJS 3.0.