PKP Sprint 2016: Documentation
With the release of OJS 3.0 on the horizon, the documentation group at the 2016 PKP Sprint focused on creating a solid foothold for OJS 3.0 documentation for users.
- Vanessa Gabler (University of Pittsburgh)
- Jeanette Hatherill (University of Ottawa)
- Jeremy Hennig (University of Alberta)
- Jessica Lang (McGill)
- Mike Nason (PKP, University of New Brunswick)
- Ramón Martins Sodoma da Fonseca (IBICT, Brazil)
- Kevin Stranack (PKP, SFU)
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.
GitBook will also allow for easier collaboration, updating, and the rapid creation of new versions of the documentation for each language and for each new version of the software (OJS 3.0, 3.1, 3.2, etc.).
The beginnings of the book can be accessed online here. 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.