This document outlines how to contribute to/modify content in the PKP Documentation Hub. First of all, thank you in advance for your contribution! Secondly, don’t be intimidated. Contributing to the docs hub can be very straightforward.
The majority of PKP documentation uses markdown syntax. Markdown is a simple, easy-to-read, easy-to-write text format that allows users to generate basic HTML without knowing HTML language itself. It uses simple tags (syntax) to format text on a website.
Knowing markdown syntax will help you immeasurably with contributing to documentation.
Here are three guides for writing markdown:
Markdown does not require a specific or specialized editor. Any basic text editor should be sufficient. If you want to try writing Markdown on your own, we would recommend using Atom. The Atom Flight Manual can get you started with this open source text editor.
All of our documents are managed using GitHub and – especially when looking to modify documents – it is essential to know a little bit about repositories, branches, and pull-requests. Don’t let the language intimidate you! It’s pretty easy. If you want to edit existing documentation or add a section or chapter to existing documentation, you can edit the document directly from the docs repository itself.
Once you’ve made your changes, it’s time to commit your changes and create a pull request. A commit is merely a change to the file you are proposing to others who use the repository. You’ll see two fields in the commit window.
The first is a very short descriptor of what you just changed. A few words should do the trick. Here are some examples:
The second window allows you to enter a more detailed description of what you changed. You might want to do this if you need to justify your changes or need to let everyone else know that a change is significant.
Below those two fields, you’ll see your committing options. If you are a member of the PKP team, you’ll see the ability to commit directly to master branch. It’s important to note that these changes are immediate, but they are also unreviewed. Please do not commit directly to master. We recommend that you always commit code via pull request.
A branch is a version of the repository that contains the changes you’ve proposed, uniquely. Since it is not part of “master,” it won’t have an impact on the way the site is built in real-time. If you create your own branch via this method, you’ll be asked to name it. Name it something simple with no spaces. A suitable way to name your branch is with the name of the document you’re adding or modifying. For example:
After naming your branch, you’ll be asked to open a “pull request.” A pull request is a request you are making for the managers of the repository to pull your changes into the master version of the doc.
You can see here that you can title your request and fill out a description of what you’ve changed. Once you’re all set, you can click the link that says “create pull request.” Once you do this, repository managers are notified of your change and can decide to merge your code with the master repository.
At the bottom of the page, you’ll see what’s known as a “diff.” A diff is just a way to see what changes you’ve made from the original code.
If you’re working on a large piece of documentation and you’re not comfortable using either the command line or the web interface for GitHub, you might want to consider using GitHub’s GitHub Desktop and the Atom text editor. With this workflow, you can “clone” a copy of the docs repository to your computer, make your edits locally (and even build a version of the Documentation Hub using Ruby, if you like) and create a pull request with your changes once you’re finished.
Once you’ve installed GitHub desktop, you should have an option while viewing any GitHub repository to “Clone or Download” and “Open in Desktop.”
GitHub desktop manages your commits and pull-requests locally. It’s especially convenient if you’re changing more than one file at once. If you have Atom installed, you can open your project with the editor directly from GitHub desktop.
In Atom, the repository directory structure is accessible on the left-hand side in the “project window.” Clicking on any title opens it in the editor and allow you to make changes. You’ll notice labels next to the files as you work. Green indicates a new file you’ve added. Yellow indicates a file you’ve changed since the last time you pulled an update from the primary repository.
If you are working on a project over time, you may want to regularly pull changes “from origin.” You can do this in GitHub desktop by clicking on the “pull from origin” button near the top right of the window. It pulls changes since the last time you pulled them (or, since the time you cloned initially).
Once you make your edits with Atom and have a document you want to submit, you’ll want to contribute it back as a “branch.”
Now that you’ve made your edits/additions and created your branch, you can commit your code. On the left side of your GitHub desktop window, you should see all the files you’re adding or changing and, at the bottom, a commit option.
The first field is for a very short descriptor of what you just changed. A few words should do the trick. Here are some examples:
The second field is for a more detailed description of what you changed. You might want to do this if you need to justify your changes or need to let everyone else know that a change is significant.
When you finish, click the button on the bottom left labelled “Commit to
Now that you’ve committed your changes, you can push your changes back to the repo with the button on the top right. It should say “Publish your Branch to Github” if it’s the first time you’ve committed that branch. It syncs versions locally and remotely with your branch changes and submits your “pull request” to managers of the Docs Hub.
This document is, necessarily, a brief introduction to using GitHub. GitHub has a tremendous amount of documentation on its use, however. If you want to read more about GitHub basics, please read “Hello, World”.
The PKP Documentation Hub utilizes Jekyll to render our markdown files into static HTML. This information isn’t super relevant to the modification of documents in general, but there are some rules for our file naming, file structure, and specific syntax you’ll need to know while working on these files. Chiefly, there are significant differences between single page documents and multi-page documents.
Single Page Documents, like this one, are rendered fully from one markdown file. The table of contents on the side of the page is created using the header tags in markdown. For example,
## The "Documentation Hub" ### Single Page Docs
If you look on the left, you’ll see that “The ‘Documentation Hub’” is currently a level 1 header and “Single Page Docs” is a level 2 header. However, this doesn’t happen by itself. When you are editing or creating a single page document, you’ll need to do the following:
--- generateHeadingToc: true ---
From here, write the document out as you would using markdown. Any level two header (e.g.:
## text) displays on the table of contents on the left as a chapter. Any level three header (e.g.:
### text) displays as a sub-chapter. Levels four and up does not display on the sidebar table of contents.
Headings should never skip a level. Do not jump from
## Heading(2) to
#### Sub-heading(3) just because you think it looks better. It is important that a sub-heading of
## Heading(2) is
### Heading(3) for accessibility.
Multi-page documents, like Learning OJS 3, are more robust directories with folders for individual languages/translations, and a single markdown file for every chapter of the document. They also contain a file called
SUMMARY.md that creates the table of contents for the book and a file called
README.md that serves as a first/landing page for your document. To create a book start with the following:
index.mdfile should contain a description of the book as well as copyright information. Look to other documents as examples. Also, if the document is available in more than one language, they should all be linked from this page.
--- isBookIndex: true ---
Unlike with a Single-page document, you no longer need to add to index.md. The rest of your document steps should be as follows:
SUMMARY.mdto allow for links to specific sections.
A note on formatting: whereas your headers in single documents create the sidebar TOC, in multi-page docs, this is handled by the
SUMMARY.mdfile. As a result, you’ll want each chapter title as an H1, with all subtitles running H2-H5. Since you can add to the TOC manually, you can include chapters there as you see fit.
Adding images to your documentation helps users more easily locate some of the features about which you are writing. Images should go in a folder named
assets. The type of document you’re working on changes where you should put your images.
assetsfolder within your main document folder. For example:
assetsfolder within the language folder of the document you’re working on. For example:
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:
In General // While any name you create should work, it’s best to keep titles short and descriptive. Always replace spaces between words with a dash.
Titles // Some example titles include:
crossref-ojs-manual. Remember that titles are part of the file path in the URL to individual docs so keep it simple.
Chapters // You might be tempted to number chapters but, if we ever need to create new chapters in between existing ones, we would need to re-number. It’s best to keep chapters in the same style as title-level names. Some examples for chapters include:
Images // Please store all images in a single “assets” folder within the language you’re working (e.g.:
en/assets/). Keep your image titles brief or with abbreviations and consistently named, so they’re easy to locate. Depending on how many images you have, numbering these might be a lot more convenient while working on the document. Listen to your heart. Some examples include:
authoring-images-01.png. If you’re putting all your imagines into only the asset folder, it’s a good idea to name your images to correspond with chapter titles.
Please read Orientation to file structure for guidance on how to configure the layout of the documentation hub. It is recommended that edits in this space be cleared via Git Issue or pull request.
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 message, and the Documentation Interest Group will convert the documentation to its final format when completed. Please do not contribute documentation in PDF, HTML, or LaTeX format.
Some documentation 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 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:
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.