Style and Format
Versioning and Updates #
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.
Image format #
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:
- for screenshots, use PNG format
- for photographs, use JPEG format
- for animations, use GIF format
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.
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.”
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.
Tips for Writing Documentation #
- Avoid duplication. If instructions already exist somewhere else that you want to include in a document, provide links instead of duplicating or reproducing the text. Linking to existing docs reduces duplication of effort when updating content. For example, if I want to write documentation for configuring a plugin, I would write it in the README file for the GitHub repository for that plugin. That way, all docs that reference that plugin can provide a link to the same information.
- Although the information you are writing about may be technical, try to write in simple, straightforward language. The PKP user community includes a variety of different people from different backgrounds and whose first language may not be the same as yours. This tutorial has tips on writing for an international audience.
- Keep in mind what group of users the documentation is for, what background and technical knowledge they may have, and what kind of information they need. User groups could include developers, system administrators, journal managers, editors, authors, and readers. Within any user group, write for the person with the most basic knowledge and experience.
- Explain and define acronyms and technical concepts.
- Break things down into simple steps and use numbered or bulleted lists whenever possible.
- Include screenshots to demonstrate, visually, how to use the software.
- Give examples to help users understand concepts.
- Try to anticipate problems and issues that the user might have. Explain how to overcome them.
You can learn more about writing good docs with these resources:
Tips for Video Documentation #
- Consider what you want the video to look like, how long it will be, and what your objective or purpose is. Create an outline and script, and practice before recording.
- Keep it short and focused, ideally 5 minutes or 10 minutes at the maximum. If you want to cover content that goes beyond that length, break the content into a few short videos.
- Ensure good audio quality by using a microphone and recording in a quiet location with no background noise or echo.
- Close all other tabs and applications and only record the window or part of your screen that is necessary to the demonstration.
- Record with standard screen dimensions (e.g. 480p, 720p)
- Test the recording software and settings before recording.
- Use narration with short sentences and simple words. Speak slowly with pauses between sentences. Remember that your viewers may not be fluent in the language you are speaking.
- Tell your audience what they are going to learn before you start. This will help them know what to expect and listen for. Follow with logical steps and only offer information that is essential for completing the task. Take time to explain concepts and steps, even when they seem obvious to you.
- End the video with a summary of your key points and offer further resources in case your viewer wants to learn more. Make sure to mention PKP.
- While you’re making the video, minimize mouse movement, as this can distract the viewer. Try using keyboard shortcuts when possible.
- If you make a mistake, just pause and continue. You can cut out the mistake later during editing.
- After recording, use annotation tools in your screencasting program to add captions, arrows, animation, or highlighting. This can help direct your viewer’s eyes, highlight important things, or further explain things.
- Give the video a clear, accurate title and an informative description
- Add captions to the video, which are text versions of the audio content, synchronized with the video. Captions help make the video accessible to people who are deaf or hard of hearing and they can improve comprehension for viewers with less fluency in the video’s language.
- Include an accurate transcript, such as an .srt file. YouTube automates this, but it does require some manual improvement. This will allow translators to more easily make subtitles in other languages.