Jump to table of contents

Contribute

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 documentation@publicknowledgeproject.org.

Ways to Contribute #

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.

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. 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.

Contribute 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.

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 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 us. Tips for making videos in Style and Format.

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, contact documentation@publicknowledgeproject.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 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.

Find a Documentation Task #

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:

  • Administrators: Administrators are responsible for PKP software installation and upgrades, ensuring the server settings are accurate, adding language files, and creating any new journals on the installation. Administrators have an understanding of and may modify system files and settings, but are not responsible for programming new features or developing the software.
  • Developers: Developers participate in the development of PKP software applications and plugins. They write and modify the code and evaluate and implement new features.
  • Application Users: Application Users represent end users of PKP software in a variety of different roles, including Journal Manager, Press Manager, Conference Manager, Editor, Reviewer, Author, Copyeditor, and Subscription Manager. They configure settings in the software applications but do not modify system files.
  • Other: Documentation tasks that are not specific to one of the above roles are added to this sheet.

For each task you can see the following information:

  • Topic, Description, and Notes explain the content of the documentation that needs to be created or updated. Read these to see what you should include and any relevant background information.
  • Action Needed indicates whether the documentation needs to be created from scratch, updated, reviewed, maintained, or moved.
  • Status notes whether the documentation is not started, in progress, or complete. Look for a task that is not started yet or one that is in progress that you want to assist with.
  • If the documentation needs to be added to an existing document or an existing document needs to be edited, the document name will be included in the Add to/Part of column and the URL for the document will be included in the New URL column.

Sign up for a Task #

  1. Select a task based on your role, interests, and experience with PKP software.
  2. Email the DIG at documentation@publicknowledgeproject.org to tell them what task you want to do. The DIG will update the spreadsheet with the information you send. This will ensure that 2 people don’t work on the same task and that you get all the information and resources you need for the task. Include the following information in your message:
    • A description of the task you’re going to do
    • Your name and contact information
    • The date you plan to finish the task
    • Any questions you have about the task or process
  3. If you have questions or need help while you’re working on your task, you can email documentation@publicknowledgeproject.org , post on the PKP Documentation Slack channel or email list, or attend a virtual documentation sprint.
  4. Once your documentation task is complete, submit it to the DIG in an appropriate format, following the instructions in this guide. If the deadline passes the DIG may contact you to ask how the task is going.

Contribute in Other Formats #

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 documentation@publicknowledgeproject.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:

  • Title of the document, chapter, section, or webpage
  • If your contribution is part of a larger document, the name of the larger document it is part of and where it belongs
  • Your name and contact information
  • A list of contributors, if applicable
  • Creation date