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 interested in documentation. The DIG is available to answer questions and offer assistance and guidance to others who want to contribute to documentation.
The DIG communicates via an email list and meet twice a month for 1.5-hour virtual documentation sprints, where we collaborate virtually on documentation.
If you want to get involved with documentation, email firstname.lastname@example.org.
There are 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.
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.
One way that PKP provides support to users, in addition to documentation, is by hosting a support forum. Users post questions about the software on the forum and members of the PKP staff and community answer. The 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.
This can include a whole document on how to use a plugin or 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.
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.
PKP software users live all over the world and speak many different languages. PKP software has been translated into over 35 languages. Most 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.
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 us. Tips for making videos in Style and Format.
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, contact email@example.com.
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 via our feedback form 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. If you want to edit a document directly, you can click the Improve this page link on any page in the Documentation Hub.
Members of the DIG review suggestions 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 task, the spreadsheet is an excellent place to start. You can also add new tasks to the spreadsheet.
Tasks are categorized by role and listed on different worksheets according to roles. You can look for tasks that match your role or experience with PKP software. The roles are as follows:
For each task you can see the following information:
We encourage users and community members to write and edit documentation in markdown and contribute through GitHub. However, contributed documentation can be created or edited in any format you want to work in, including a .doc or .odt text document, a Google doc, or an email, and the DIG will convert the documentation to markdown. Please do not contribute documentation in PDF, HTML, or LaTeX format.
Some contributors prefer to create or edit documentation in a Word, Open Document, Google Doc, or another format. If you’re creating documentation with a group of people, it can be easier to use a Google Doc than GitHub.
If you have created documentation in one of these other formats, you can email the file as an attachment or link to a shared document to firstname.lastname@example.org. If you created documentation as a Google doc, you should send the link in an email message.
If you are editing an existing document, try to make it as clear as possible what you have changed.
Please include the following information in either the file name or the file contents: