These guidelines are for all contributors to Public Knowledge Project (PKP) documentation, including PKP staff and committee members, users of the software, journal managers, system administrators, and developers. Whether you are just starting to use PKP software or have been using it for many years, you have a unique perspective and valuable information to share with the community.
Documentation is essential to the users of Open Journal Systems (OJS), Open Monograph Press (OMP), Open Conference Systems (OCS), and other software developed by PKP. It is often the first thing that users look at when they’re getting started, trying to troubleshoot a problem, or learning how to use a new feature or version of the software. Creating and updating documentation is a precious contribution to the PKP user community.
First of all, thank you in advance for your contribution! Secondly, contributing can be very easy. These guidelines are essential reading for anyone who would like to contribute to PKP documentation. They outline different types of documentation, ways to contribute, how to find and complete a documentation task, style and formatting, tips and resources, and copyright policies.
Most of PKP’s existing documentation is on the PKP website. It consists of the following:
PKP software documentation is created and maintained by PKP staff, users, and developers. It’s coordinated by the Documentation Interest Group (DIG), which is made up of PKP staff, users, and developers who are especially interested in documentation. All of us are available to answer questions and offer assistance and guidance to other folks who want to contribute to documentation.
We communicate on a Slack channel and meet twice a month for 2-hour virtual documentation sprints, where we collaborate virtually on documentation.
If you want to be added to the Slack channel, participate in a sprint, or otherwise get involved with documentation, email firstname.lastname@example.org.
There many ways to contribute to PKP software documentation whether you want to write, edit, or update any piece – big or small – of a specific document.
Update existing documentation // Most PKP software is consistently under development. Documentation requires the same. Depending on how much the software has changed since the last revision, updating documentation can involve making a few minor changes or significant rewriting. A list of documents flagged for an update is on the PKP Documentation Tasks spreadsheet, explained below. If you are new to writing documentation, updating docs is often a good place to start.
Transform support forum topics into documentation // One way that PKP provides support to users, in addition to documentation, is by hosting a [support forum] (https://forum.pkp.sfu.ca/). Users post questions about the software on the forum and members of the PKP staff and community answer the questions. The support forum is a rich resource for unique, advanced information for customizations and troubleshooting the software which may be missing from the standard documentation, especially regarding new features. It can be difficult, however, to find relevant information on the forum. You can contribute to PKP documentation by noting questions on the forum that are not answered in documentation (especially common questions) and transferring the answers to existing documentation or sometimes creating new documentation.
Contribute new documentation // This can include a whole document on how to use a plugin or software tool, or it could just be writing a chapter or section in a larger document, but it means creating original documentation. To do this, you should have a solid understanding of the tool or feature for which you are writing instructions. We have a list of desired documentation, or you may wish to contribute your own. Instructions on how to access the list and format guidelines are available below.
Review and edit // When PKP documentation has been created or updated, it goes through a review process, in which someone reads it and offers critical feedback on accuracy, clarity, and completeness. If you enjoy proofreading or editing or are new to documentation, this could be the right task for you. The PKP Documentation Tasks spreadsheet (explained below) has labels for which docs need review.
Translate // PKP software users live all over the world and speak many different languages. PKP software has been translated into over 35 languages. Most PKP software documentation is written in English initially and needs translation into other languages. If you are a fluent reader of English and fluent writer of another language, translating documentation into the other language is a valuable contribution to the documentation project.
Make an instructional video or screencast // PKP has a set of videos called PKP School on how to use OJS and contribute to OJS journals, and we are building a collection of other videos about PKP software. If you’re interested in making video tutorials on using PKP software, you can volunteer to help make PKP School videos, or you can make your own video on how to carry out a task or set of tasks in one of the PKP software tools. To assist with PKP School videos, contact Kevin Stranack at email@example.com. Guidelines for making videos are below.
Share your local documentation with the PKP user community // Have you made a document about PKP software that is specific to your local institution, journal, conference, or press? It may be useful to the broader PKP user community if it provides information and instructions not available elsewhere or if other users are looking for examples of institutional or journal-specific documentation. We are building a collection of external documentation. To add to it, please contact firstname.lastname@example.org.
Identify documentation that is missing or needs improvement // If you notice something that there should be documentation for or existing documentation that needs to be corrected, updated, or explained more clearly, we want to know. You can send your suggestion to email@example.com or file an issue in the Github PKP Docs repository. To file an issue in the repository, you first have to create a Github account and sign in.
Members of the Documentation Interest Group review suggestions regularly and add them to lists of potential tasks. Please provide as much detail as possible in your suggestion.
PKP keeps track of documentation that needs to be created, updated, and reviewed on a shared spreadsheet that’s maintained by the DIG. If you’re looking for a documentation task to do, the spreadsheet is an excellent place to start. You can also add new tasks.
Tasks are categorized by role and listed on different worksheets according to role. You can look for tasks that match your role or background with PKP software. The roles are as follows:
For each task you can see the following information:
You can learn more about writing good docs with this Documentation Guide by WritetheDocs.
Most documentation is updated continually by contributors as needed. In the event of a major software release that might make older docs irrelevant (e.g., OJS 3.1 -> OJS 3.2) PKP strives to update the materials before or as-close-to release as possible.
When making changes related to minor software releases (e.g., OJS 3.1.1 -> 3.1.2), it is generally best to explain differences between versions explicitly in the document. For example:
“In OJS releases 3.0 to 3.1.0, you cannot assign a user to review a submission if they are also an editor of the submission. However, starting with OJS 3.1.1, you can assign a user to review a submission if they are also an editor of the submission.”
Older versions of the documentation are accessible – via GitHub branches – for major-version documents in the Documentation Hub.
All PKP documentation is licensed under a Creative Commons BY license. Contributors are acknowledged for contributions that they make, but the documents are owned by the Public Knowledge Project and Simon Fraser University Library.
If you wish to retain ownership of documentation about PKP software that you create and contribute to the PKP project, you can host it in your own repository or on your website, and we can link to it.