diff --git a/contributing/en/README.md b/contributing/en/README.md index ad3c2fde97a2..ad55a147793e 100644 --- a/contributing/en/README.md +++ b/contributing/en/README.md @@ -5,7 +5,7 @@ description: A guide on how to contribute to PKP documentation about OJS, OMP, a # Introduction: Guidelines for Contributing to PKP Documentation -This guide explain everything you need to know to contribute to the Public Knowledge Project's (PKP's) documentation, including how to get involved, how to edit and create documentation in PKP's Github repository, how to find and complete a documentation task, style and formatting tips, and copyright policies. +This guide explains everything you need to know to contribute to the Public Knowledge Project's (PKP's) documentation, including how to get involved, how to find and complete a documentation task, how to edit and create documentation in PKP's GitHub repository, tips on style and formatting, and copyright policies. PKP creates and maintains extensive documentation about our software applications Open Journal Systems (OJS), Open Monograph Press (OMP), and Open Preprint Systems (OPS), as well as on scholarly publishing best practices. All of our documentation is available in the [PKP Docs Hub](https://docs.pkp.sfu.ca/index.html) and includes both user guides and videos. diff --git a/contributing/en/SUMMARY.md b/contributing/en/SUMMARY.md index e35f8d8813ec..8ec625c47b30 100644 --- a/contributing/en/SUMMARY.md +++ b/contributing/en/SUMMARY.md @@ -7,13 +7,16 @@ * [Sign up for a Task](./contribute.md#sign-up-for-a-task) * [Contribute in Other Formats](./contribute.md#contribute-in-other-formats) * [Getting Started](./gettingstarted.md) + * [Markdown](./gettingstarted.md#markdown) * [File Structure](./gettingstarted.md#file-structure) - * [Branches and Pull Requests](./gettingstarted.md#branches-and-pull-requests) * [File Naming Conventions](./gettingstarted.md#file-naming-conventions) - * [Markdown](./gettingstarted.md#markdown) - * [Editing with GitHub Desktop and Atom](./gettingstarted.md#editing-with-github-desktop-and-atom) + * [GitHub Basics](./gettingstarted.md#github-basics) + * [Editing on GitHub](./gettingstarted.md#editing-on-github) + * [Editing on GitHub](./gettingstarted.md#editing-on-the-pkp-docs-hub) + * [Editing with GitHub Desktop](./gettingstarted.md#editing-with-github-desktop) * [Contribute in Other Formats](./gettingstarted.md#contribute-in-other-formats) * [Create and Edit Documentation](./create-and-edit.md) + * [File Naming Conventions](./create-and-edit.md#file-naming-conventions) * [Edit a Document](./create-and-edit.md#edit-a-document) * [Create a Document](./create-and-edit.md#create-a-document) * [Adding/Replacing Images](./create-and-edit.md#addingreplacing-images) diff --git a/contributing/en/assets/Github-dash-2.png b/contributing/en/assets/Github-dash-2.png deleted file mode 100644 index 0f18e58a940f..000000000000 Binary files a/contributing/en/assets/Github-dash-2.png and /dev/null differ diff --git a/contributing/en/assets/Github-dash-branch-menu.png b/contributing/en/assets/Github-dash-branch-menu.png deleted file mode 100644 index c9c97bc410af..000000000000 Binary files a/contributing/en/assets/Github-dash-branch-menu.png and /dev/null differ diff --git a/contributing/en/assets/Github-dash-lang.png b/contributing/en/assets/Github-dash-lang.png deleted file mode 100644 index 57abad684c14..000000000000 Binary files a/contributing/en/assets/Github-dash-lang.png and /dev/null differ diff --git a/contributing/en/assets/Github-dash.png b/contributing/en/assets/Github-dash.png deleted file mode 100644 index 74a72b93a95b..000000000000 Binary files a/contributing/en/assets/Github-dash.png and /dev/null differ diff --git a/contributing/en/assets/Github-notice.png b/contributing/en/assets/Github-notice.png deleted file mode 100644 index 59b94191584c..000000000000 Binary files a/contributing/en/assets/Github-notice.png and /dev/null differ diff --git a/contributing/en/assets/Github-readme.png b/contributing/en/assets/Github-readme.png deleted file mode 100644 index 79b28fbf8cb6..000000000000 Binary files a/contributing/en/assets/Github-readme.png and /dev/null differ diff --git a/contributing/en/assets/contrib-05b.png b/contributing/en/assets/contrib-05b.png new file mode 100644 index 000000000000..2da7651e1126 Binary files /dev/null and b/contributing/en/assets/contrib-05b.png differ diff --git a/contributing/en/assets/contrib-edit-directly.gif b/contributing/en/assets/contrib-edit-directly.gif new file mode 100644 index 000000000000..981be1c85e9c Binary files /dev/null and b/contributing/en/assets/contrib-edit-directly.gif differ diff --git a/contributing/en/assets/contrib-edit-this-page.png b/contributing/en/assets/contrib-edit-this-page.png new file mode 100644 index 000000000000..11d9ac417c97 Binary files /dev/null and b/contributing/en/assets/contrib-edit-this-page.png differ diff --git a/contributing/en/assets/contrib-github-folders-languages.png b/contributing/en/assets/contrib-github-folders-languages.png new file mode 100644 index 000000000000..a7f851fb972f Binary files /dev/null and b/contributing/en/assets/contrib-github-folders-languages.png differ diff --git a/contributing/en/assets/contrib-github-folders-multipage-structure.png b/contributing/en/assets/contrib-github-folders-multipage-structure.png new file mode 100644 index 000000000000..26ea7a769221 Binary files /dev/null and b/contributing/en/assets/contrib-github-folders-multipage-structure.png differ diff --git a/contributing/en/assets/contrib-github-folders-versions.png b/contributing/en/assets/contrib-github-folders-versions.png new file mode 100644 index 000000000000..dc056f494b23 Binary files /dev/null and b/contributing/en/assets/contrib-github-folders-versions.png differ diff --git a/contributing/en/assets/contrib-github-folders.png b/contributing/en/assets/contrib-github-folders.png new file mode 100644 index 000000000000..92fcbdcd8052 Binary files /dev/null and b/contributing/en/assets/contrib-github-folders.png differ diff --git a/contributing/en/assets/contrib-github-fork.gif b/contributing/en/assets/contrib-github-fork.gif new file mode 100644 index 000000000000..b3c74dcb5103 Binary files /dev/null and b/contributing/en/assets/contrib-github-fork.gif differ diff --git a/contributing/en/assets/contrib-index-file.png b/contributing/en/assets/contrib-index-file.png new file mode 100644 index 000000000000..30c5712adc34 Binary files /dev/null and b/contributing/en/assets/contrib-index-file.png differ diff --git a/contributing/en/assets/index-file.png b/contributing/en/assets/index-file.png deleted file mode 100644 index 12aedbc3198a..000000000000 Binary files a/contributing/en/assets/index-file.png and /dev/null differ diff --git a/contributing/en/contribute.md b/contributing/en/contribute.md index e3f197c77d08..fa41dcdb9ae9 100644 --- a/contributing/en/contribute.md +++ b/contributing/en/contribute.md @@ -87,7 +87,7 @@ For each task you can see the following information: ## 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. +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. diff --git a/contributing/en/create-and-edit.md b/contributing/en/create-and-edit.md index fb32bf748157..328bf3c4124d 100644 --- a/contributing/en/create-and-edit.md +++ b/contributing/en/create-and-edit.md @@ -7,26 +7,17 @@ showPageTOC: true Now that you understand the basics of GitHub, this chapter explains how to add new documents and edit documents in the repository. -## Edit a Document +## File Naming Conventions -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. +**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. -1. Create a [GitHub](https://github.com) account if you do not already have one and log in. -2. Navigate to [the repository in GitHub](https://github.com/pkp/pkp-docs). -3. Follow the directory structure in GitHub until you see the file you want to edit. -4. Click the filename to view that individual file. -5. From there, on the top right of the document window, you should see a small pencil icon. -6. Click that button to open up a plain text editor for the document within GitHub itself. -7. Edit the document. +**Titles**: Some example titles include: learning-ojs, pkp-theming-guide, crossref-ojs-manual. Remember that titles are part of the file path in the URL to individual docs so keep it simple. -
- -
File edit menu in GitHub.
-
+**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: getting-started.md, troubleshooting.md, data-import-and-export.md. + +**Images**: 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: contrib-01.png, authoring-images-01.png. If you’re putting all your images into only the asset folder, it’s a good idea to name your images to correspond with chapter titles. -If your edits requires you to replace or add images, see section on Adding/Replacing images. +Note that file names are case sensitive, so if the image is saved as learning-ojs3.1-jm-settings-workflow-email-templates.png and you reference Learning-OJS3.1-jm-settings-workflow-email-templates.png in the document, the image will not display. ## Create a Document @@ -37,7 +28,7 @@ When you create a new document, you need to decided whether to make it a _single ### Single Page Docs -Single page documents 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: +Single page documents 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" @@ -56,16 +47,17 @@ To create a new single page document in GitHub: ``` --- generateHeadingToc: true +showPageTOC: 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. +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 do not display on the sidebar table of contents. > Headings should never skip a level. Do not jump from `## Heading` (2) to `#### Sub-heading` (4). It is important that a sub-heading of `## Heading` (2) is `### Heading` (3) for accessibility. ### Multi-page Docs -Multi-page documents, like [Learning OJS 3](./learning-ojs), 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 document and a file called `README.md` that serves as a first/landing page for your document. To create a multi-page document start with the following: +Multi-page documents, like [Learning OJS 3](./learning-ojs), 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 document and a file called `README.md` that serves as a first/landing page for your document. To create a multi-page document start with the following: 1. In the pkp-docs repository, click Create New File. You will create the new folder for the document as you create the file. 2. Enter the name of the document folder and then /. This will automatically create the folder. @@ -84,7 +76,7 @@ Unlike with a single-page document, you no longer need to add to index.md. The r 1. Create a folder for the [language of your document](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) using the two-letter ISO 639-1 code (e.g.,: en, fr, es, ar). 2. Create a file called `SUMMARY.md` - - `SUMMARY.md` is the file that determines the display of the table of contents for your document. The markdown list hierarchy determines the nesting of contents titles in your sidebar. Each chapter title is written as a link to either a single markdown file per chapter _or_ as a link to a specific heading within that markdown file. You can fill in all of the chapter and section links after you have created the chapter files. + - `SUMMARY.md` is the file that determines the display of the table of contents for your document. The Markdown list hierarchy determines the nesting of contents titles in your sidebar. Each chapter title is written as a link to either a single Markdown file per chapter _or_ as a link to a specific heading within that Markdown file. You can fill in all of the chapter and section links after you have created the chapter files. - a chapter link would look like: `- [Statistics](statistics.md)` - a heading inside that chapter would look like: `- [Definitions](./statistics.md#definitions)` @@ -130,7 +122,7 @@ Save the README file when it is complete. #### Create chapter files -Next you can create a separate file for each chapter in the guide and add content to each chapter. Each full chapter of a multi-page document should be a single markdown file. +Next you can create a separate file for each chapter in the guide and add content to each chapter. Each full chapter of a multi-page document should be a single Markdown file. Every chapter file should have Title front matter (metadata), which can include the document title, and Description front matter, which should give a summary of the document and include main keywords that would be searched. For example, if the document is "Designing Your OJS Journal" and the chapter is "Inclusive and Accessible Theming," the Title could be as follows: diff --git a/contributing/en/gettingstarted.md b/contributing/en/gettingstarted.md index 9ade913c0d10..2a39d3dac90d 100644 --- a/contributing/en/gettingstarted.md +++ b/contributing/en/gettingstarted.md @@ -4,85 +4,133 @@ showPageTOC: true --- # Getting Started -Most of PKP’s documentation is hosted and managed in a GitHub repository called the PKP Documentation Hub and is built using an open-source tool called [Jekyll](https://jekyllrb.com/). GitHub is a collaborative version control system that manages and stores revisions of a project. To learn more about GitHub and Git, watch this ["What Is Git and Github?" video](https://www.youtube.com/watch?v=uUuTYDg9XoI) or this ["Git and Github for Poets" video](https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV). +Most of PKP’s documentation is [hosted and managed in the pkp-docs GitHub repository](https://github.com/pkp/pkp-docs) and is published to the [web-based PKP Docs Hub](https://docs.pkp.sfu.ca/) using an open source tool called [Jekyll](https://jekyllrb.com/). GitHub is a collaborative version control system that manages and stores revisions of a project. -The content files that make up PKP’s documentation are stored in the [Documentation Hub repository](https://github.com/pkp/pkp-docs) and anyone with a GitHub account can edit and add documents to the repository. This chapter explains the important things you will need to know when working on GitHub. +The content files that make up PKP’s documentation are stored in the [pkp-docs repository](https://github.com/pkp/pkp-docs), and anyone with a GitHub account can edit and add documents. This chapter explains the important things you will need to know when working with PKP documentation and GitHub. -If you don’t have a GitHub account already, begin by [creating an account](https://github.com/join?source=header-home). +## Markdown -## File Structure +PKP documentation files are all in a format called Markdown, a simple, easy-to-read, easy-to-write text format that allows users to generate basic HTML without knowing HTML itself. It uses simple tags to format text on a website. Content files written in Markdown use the `.md` file extension. + +Here are some examples of Markdown: + +____ + +``` +I am _really_ looking forward to learning Markdown. +``` +The pair of `_` symbols surrounding the text generate italics for emphasis that are equivalent to the `` element in HTML. +____ + +``` +## About the Documentation Hub +``` +The ## creates a header that is equivalent to the `

` element in HTML. +____ + +``` +Here's a helpful [guide to Markdown](https://daringfireball.net/projects/markdown/syntax). +``` +The `[]()` symbols generate linked text that is equivalent to the ` element in HTML. +____ -Each folder in the PKP Documentation Hub repository represents a document. -![Docs hub folder structure in Github.](./assets/Github-dash.png) +To learn more, consult these three guides for writing Markdown: -Short documents consist of a single markdown file and may have an “assets” folder of images. All content is contained in the `index.md` file and the table of contents on the side of the page is created using the header tags in markdown. +- [Daring Fireball Markdown Syntax](https://daringfireball.net/projects/markdown/syntax) +- [Mastering GitHub Flavoured Markdown](https://guides.github.com/features/mastering-markdown/) +- [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) -![Index.md page of Starting a Journal document.](./assets/index-file.png) -Longer documents consist of multiple chapter files, a README file, a SUMMARY file, and an assets folder. Content is stored in the chapter files and the README file acts as a summary page for the document. The SUMMARY file creates the table of contents. +## File Structure -**All files created will need to have a .md ending** +Each folder in the pkp-docs repository represents one document, meaning one guide, which may have multiple "chapters" represented by multiple files. For instance, this guide to contributing to PKP's documentation resides in the `contributing` folder. -![Learning OJS guide folder structure.](./assets/Github-dash-2.png) +![Docs hub folder structure in GitHub.](./assets/contrib-github-folders.png) -If the document exists (or will exist) in more than one language, there will be a separate folder of these files for each language version. +Within each document's main folder is an `index.md` Markdown file that contains information about the document's title, description, contributors, version, and languages. -![Learning OJS guide language folders.](./assets/Github-dash-lang.png) +Single-page documents consist of only the single Markdown file `index.md` and, if necessary, an `/assets` folder for images. All document content is contained in the `index.md` file. -### README File +Sub-folders may include separate folders for each language version, named according to the two-character ISO code for the language, e.g., `en` for the English version and `pt` for the Portuguese version. -The README.md file should include a brief introduction regarding the document, a list of contributors, and a release date. +![Google Scholar guide with language folders.](./assets/contrib-github-folders-languages.png) -![Readme file for the Using the Paypal Plugin guide.](./assets/Github-readme.png) +Additional sub-folders may include separate folders for previous software versions. When there are previous version folders, the top-level language folders will include documentation for the current version. -## Branches and Pull Requests +![Learning OJS guide with version and language folders.](./assets/contrib-github-folders-versions.png) -A branch is a version of the repository that contains the changes you’ve proposed, uniquely. Since it is not part of "main", it won’t have an impact on the way the site is built in real-time. +Within sub-folders, longer multi-page documents consist of a README file, a SUMMARY file, multiple content files ("chapters") in `.md` format, and an `/assets` folder that contains the document's images. The README file is the main landing page for the document, the SUMMARY file creates the table of contents, and the document content is stored in the separate chapter files. -As most users will not have direct access to make changes to the PKP repository, they will need to create a branch to make changes. If you do not have full permission you will come across the message box that says: "You're editing a file in a project you don't have write access to. Submitting a change to this file will write it to a new branch in your fork, so you can send a pull request". +**All content files must be written in Markdown and have the `.md` file extension.** -![Editing access warning message.](./assets/Github-notice.png) +![Contributing guide folder structure.](./assets/contrib-github-folders-multipage-structure.png) -A branch can be created on your own repository or automatically generated when you try to make a change on the PKP repository. +Notice that the folder and file structure in the repository controls the URL structure for locations of documents on the Docs Hub. For instance, the README.md landing page of "Style and Format" chapter of this document on contributing to PKP documentation is located in the directory `/contributing/en/style-and-format`, and the content of that file is what you will see when you navigate to the URL `https://docs.pkp.sfu.ca/contributing/en/style-and-format` on the Docs Hub. ## File Naming Conventions -**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. +**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: `learning-ojs`, `pkp-theming-guide`, `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: `getting-started.md`, `troubleshooting.md`, `data-import-and-export.md`. -**Images**: 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: `contrib-01.png`, `authoring-images-01.png`. If you’re putting all your images into only the asset folder, it’s a good idea to name your images to correspond with chapter titles. +**Images**: Store all images in a single "assets" folder in the language folder you’re working (e.g.,: `/learning-ojs/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: `contrib-01.png`, `authoring-images-01.png`. If you’re putting all your images into only the asset folder, it’s a good idea to name your images to correspond with chapter titles. -Note that file names are case sensitive, so if the image is saved as `learning-ojs3.1-jm-settings-workflow-email-templates.png` and you reference `learning-ojs3.1-jm-settings-workflow-email-templates.png` in the document, the image will not display. +Note that file names are case sensitive, so if the image is saved as `learning-ojs3.1-jm-settings-workflow-email-templates.png` and you reference `Learning-OJS3.1-jm-Settings-Workflow-Email-Templates.png` in the document, the image will not display. -## Markdown -The files are all in a format called Markdown, a simple, easy-to-read, easy-to-write text format that allows users to generate basic HTML without knowing HTML itself. It uses simple tags to format text on a website. +## GitHub Basics -This is an example of markdown: +The PKP Documentation Hub is stored and managed in the [pkp-docs GitHub repository](https://github.com/pkp/pkp-docs), and we therefore recommend that documentation contributors have a GitHub account and be able to execute basic functions in GitHub, although there are also other ways to contribute, as described below. -``` -## The "Documentation Hub" +Some key GitHub terms are defined in the [GitHub Docs Glossary](https://docs.github.com/en/get-started/quickstart/github-glossary) and linked to below. To learn even more about GitHub and Git, watch this ["What Is Git and GitHub?" video](https://www.youtube.com/watch?v=uUuTYDg9XoI) or this ["Git and GitHub for Poets" video](https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV) or consult the [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) quickstart guide. -### Single Page Docs -``` +To begin contributing to PKP Documentation, you will need to [create a GitHub account](https://github.com/join?source=header-home) if you don't already have one. -Here are three guides for writing markdown: +Also, since most contributors will not have direct edit access to PKP documents, you will need to create a [fork](https://docs.github.com/en/get-started/quickstart/github-glossary#fork) of the [pkp-docs repository](https://github.com/pkp/pkp-docs) in your own account so that you can [commit](https://docs.github.com/en/get-started/quickstart/github-glossary#commit) changes to your own fork and then submit a [pull request](https://docs.github.com/en/get-started/quickstart/github-glossary#pull-request) via one of the methods described below so that your work can be reviewed, merged, and published. -- [Daring Fireball Markdown Syntax](https://daringfireball.net/projects/markdown/syntax) -- [Mastering GitHub Flavoured Markdown](https://guides.github.com/features/mastering-markdown/) -- [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) +![Forking the PKP Docs repository](./assets/contrib-github-fork.gif) + + +## Editing on GitHub -## Editing with GitHub Desktop and Atom +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 on github.com. -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, consider using [GitHub Desktop](https://desktop.github.com/) and the [Atom](https://atom.io/) 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. +1. Create a [GitHub](https://github.com) account if you do not already have one and log in. +2. [Fork](https://docs.github.com/en/get-started/quickstart/github-glossary#fork) the [pkp-docs GitHub repository](https://github.com/pkp/pkp-docs) to your own account. +2. Navigate to [the Docs Hub repository in GitHub](https://github.com/pkp/pkp-docs). +3. Follow the directory structure in GitHub until you see the file you want to edit. +4. Click the filename to view that individual file. +5. From there, on the top right of the document window, you will see a small pencil icon. +6. Click the pencil icon to open up a plain text editor for the document within GitHub itself. +7. Edit the document. When you are finished, click the green "Commit Changes" button in the top right. Your changes will be saved to a new [branch](https://docs.github.com/en/get-started/quickstart/github-glossary#branch) in your fork of the pkp-docs repository. +8. Create a [pull request](https://docs.github.com/en/get-started/quickstart/github-glossary#pull-request) for your changes. Someone will review your changes, merge them into the pkp-docs repository, and publish them to the Docs Hub. -Once you've installed GitHub desktop, you should have an option while viewing any GitHub repository to "Code" and "Open with GitHub Desktop". -1. Navigate to the repository you want to clone. +
+ +
File edit menu in GitHub.
+
+ + +## Editing on the PKP Docs Hub + +You can also edit existing documentation directly from the [PKP Docs Hub](https://docs.pkp.sfu.ca/) on the web. Clicking "Make a suggestion" will bring up an email contact form where you can write to PKP to ask for a change to documentation. Clicking "Edit this page" will allow you to make edits in the pkp-docs GitHub repository exactly as though you were editing on GitHub.com as described above. + + +## Editing with GitHub Desktop + +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, consider using [GitHub Desktop](https://desktop.github.com/) and a [compatible text editor](https://docs.github.com/en/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop) of your choice. With this workflow, you can clone a copy of the docs repository to your computer, make your edits locally, and create a pull request with your changes once you're finished. + +GitHub Desktop is free to install and is available for both Mac and Windows, but you will also need to choose a text editor to use with it, and many of these require purchase. See the [list of text editors that are supported by GitHub Desktop](https://docs.github.com/en/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop) for Mac and Windows and be sure to download and install one that you're comfortable with. If you're not sure which to choose, try [BBEdit for Mac](http://www.barebones.com/products/bbedit/) or [Notepad++ for Windows](https://notepad-plus-plus.org/). + +Once you've installed GitHub Desktop and have [configured your default text editor](https://docs.github.com/en/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop#configuring-a-default-editor), you should have an option while viewing any GitHub repository on github.com to "Open with GitHub Desktop". + +1. Navigate to the repository you want to clone, e.g., [https://github.com/pkp/pkp-docs](https://github.com/pkp/pkp-docs) 2. Click on the green button on the right that says "Code." 3. Select the "Open with GitHub Desktop" option. @@ -94,21 +142,19 @@ You'll be prompted to choose a download location for your copy of the repository It'll take a few minutes for all the files to download. -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. +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 like, you can open content files in a text editor directly from GitHub Desktop. -1. Open GitHub desktop. +1. Open GitHub Desktop. 2. Right click on the name of the repository in which you want to work. -3. Select "Open in Atom." - -![Open project from Github Desktop.](./assets/contrib-05.png) +3. Select the option to open the repository in your default text editor. -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 the colors of the filenames change 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. +![Open project from GitHub Desktop.](./assets/contrib-05b.png) -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 the "Fetch origin" button at the top of the window. It pulls changes since the last time you pulled them (or, since the time you cloned initially). +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 the "Fetch origin" button at the top of the window. It pulls changes since the last time you pulled them (or, since the time you cloned initially). ![Fetch origin updates from GitHub.](./assets/contrib-06a.png) -Make sure you've saved your changes in Atom. Then you'll see a list of your changed files in GitHub Desktop. A green plus sign indicates a file you're adding; an orange dot denotes a file you've modified. +Whenever you make changes, you'll see a list of your changed files in GitHub Desktop. A green plus sign indicates a file you're adding; an orange dot denotes a file you've modified, and a red minus sign denotes a file you've removed or renamed. In the bottom left-hand corner, you'll see a warning that you don't have write access to pkp-docs. GitHub Desktop invites you to create a fork by clicking on the hyperlink. @@ -118,7 +164,7 @@ On the popup message, click the **Fork this Repository** button. GitHub then ask ![Contribute to the parent project.](./assets/contrib-07b.png) -Once you've finished making your edits with Atom and have a document you want to submit, you'll need to contribute it back as a "branch." +Once you've finished making your edits and have a document you want to submit, you'll need to contribute it back as a "branch." 1. In GitHub Desktop, click on the "Current Branch" button. 2. Click "New Branch" @@ -134,7 +180,7 @@ Once you've finished making your edits with Atom and have a document you want to 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. -![Commit to master button in Github desktop.](./assets/contrib-08.png) +![Commit to master button in GitHub Desktop.](./assets/contrib-08.png) The Summary field is for a very short descriptor of what you just changed. A few words should do the trick. Here are some examples: @@ -155,7 +201,7 @@ This document is, necessarily, a brief introduction to using GitHub. GitHub has ## 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. Do not contribute documentation in PDF, HTML, or LaTeX format. +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. 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. diff --git a/contributing/en/style-and-format.md b/contributing/en/style-and-format.md index 85d650cfcd42..3957bfa01b8c 100644 --- a/contributing/en/style-and-format.md +++ b/contributing/en/style-and-format.md @@ -141,7 +141,7 @@ If documentation they contributed changes substantially over time, their names m ## 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](https://www.linux.com/tutorials/technical-writing-international-audience/) has tips on writing for an international audience. +- 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 from the Linux Foundation](https://www.linux.com/tutorials/technical-writing-international-audience/) 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. @@ -149,10 +149,10 @@ If documentation they contributed changes substantially over time, their names m - 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: +You can learn more about writing good documentation with these resources: - [Documentation Guide by WritetheDocs](http://www.writethedocs.org/guide/) -- [Mailchimp Content Style Guide](https://styleguide.mailchimp.com/writing-technical-content/) +- [Mailchimp Content Style Guide](https://styleguide.mailchimp.com) ## Tips for Video Documentation