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.
Images are restricted to 848 pixels in width on display. Where possible, try to limit your file size by keeping your images below that width. The format should follow these guidelines:
When you take screenshots, do not include the menu and broader elements of the interface unless it is necessary. This lessens the need to replace screenshots when the software interface changes.
PKP’s documentation uses Canadian spelling. For example, use “centre” instead of “center.”
When using pronouns to refer to a generic user, use gender-neutral pronouns such as “they,” “their,” and “them.” Use “they” instead of “he” or “she.” Use “their” instead of “his” or “her.” Use “them” instead of “her” or “him.” Use “themselves” instead of “himself” or “herself.”
Users who navigate using a screen reader must be able to unambiguously understand the purpose of the link and skip links they are not interested in. To achieve this, link text needs to be:
Descriptive. Provide URL text rather than adding plain URL. E.g.:
Do not use: “Read about OJS plugins at https://docs.pkp.sfu.ca/learning-ojs/en/settings-website#plugins”.
Use instead: “Read about OJS plugins in the Learning OJS: plugins section”.
When writing URL text, make sure it can be understood without additional context. E.g.:
Do not use: “Click here to read about OJS plugins”.
Use instead: “More information is available in the Learning OJS: plugins section”.
Concise. Use keyword(s) as linked text rather than longer sentences. E.g.:
Do not use: “More information is available in the Learning OJS: plugins section which lists available OJS plugins”.
Use instead: “More information is available in the Learning OJS: plugins section”.
Unique. Avoid similarly named hyperlinks if they link to different places. E.g.:
Do not use the generic “Learning OJS” for links referring to different sections of the guide.
Use instead: “More information is available in the Learning OJS: plugins section”.
To facilitate navigation by tabbing or with a screen reader, headings should be used in hierarchical order, without skipping.
Markdown headings correspond to HTML headings as follows:
<h1> = #
<h2> = ##
<h3> = ###
… etc.
The headings are nested according to their rank or level. E.g. <h1> or # is the highest level in importance, followed by <h2> or ## etc.
Avoid skipping headings in a document structure to prevent confusion, even if you prefer the visual presentation. A <h2> must be followed by a <h3> as the next subheading in the same section. However, it is acceptable to have a <h4> followed directly by a <h2> when it opens a new section, as long as <h4> closes the previous one.
Only one <h1> or # heading should be used per document, because it serves as the document title. Therefore most sections within a Docs Hub page will start with <h2> or ##.
When creating documentation in Markdown, you have the option of using coloured content blocks to highlight information for the reader. There are three options available: a “tip” block, a “notice” block, and a “warning” block. This will not add any semantic markup to the text blocks, and will only add coloured backgrounds to visually highlight the text.
We recommend using each style for the following types of content:
To add a blockquote style to a section of text, use the blockquote Markdown styling by starting a section of text with a > character. Then, add the styling on the line after the text you are highlighting in braces. You can include other Markdown formatting, like bold text or links, in these blockquotes as well.
For example, if you wanted a block of text to have the warning style, you would use the following syntax:
> Documentation for the REST APIs in OMP and OPS is not yet available. These applications share many of the same endpoints as OJS, but the documentation has not yet been prepared.
{:.notice}
The examples below demonstrate what each style will look like in the documentation hub.
All of the form field components can be seen in the UI Library.
Documentation for the REST APIs in OMP and OPS is not yet available. These applications share many of the same endpoints as OJS, but the documentation has not yet been prepared.
Do not skip this step. An upgrade can fail for many reasons. Without a backup you may permanently lose data.
When linking to external files not hosted in the Docs Hub, consider the following:
Contributors to a document, including authors and translators, can be noted in the Index.md file for a document. See this example for how contributor credits should be formatted.
If documentation they contributed changes substantially over time, their names may be removed.
You can learn more about writing good docs with these resources: