Contributing to the ClassicPress documentation

Our documentation site at https://docs.classicpress.net is now serving content based on the Markdown files stored at https://github.com/ClassicPress/ClassicPress-docs, and we are ready to welcome your contributions here, such as cleaning up outdated or duplicated content.

How to contribute

At the bottom of each page on docs.classicpress.net, you will see a new link to “Edit this page on GitHub”.

When you click this link, you’ll be prompted to log in to GitHub and submit a change back to the original version of the file as a GitHub pull request.

The idea of this contribution workflow is that anyone can propose changes to the documentation site without requiring special access. Also, via issues and pull requests, GitHub gives us the tools to discuss and iterate on any changes before accepting them, and a full, public revision history of the content stored there.

Any edits that follow basic Markdown syntax can be completed and previewed from within the GitHub web interface only, which simplifies things as compared to the full GitHub workflow for code.

I think using the GitHub web interface to make an improvement to our documentation would be a good topic to write a tutorial on :wink:

Some context

Previously, our documentation site has just been a normal, vanilla ClassicPress site. This has worked well but it has meant that anyone who contributes to our documentation needs to have a privileged user account on the site.

This new contribution workflow is an experiment, but I hope it will allow more people to contribute to our documentation and also serve as the base for further efforts here, like building a code reference.

These changes have previously been planned and discussed in Slack in the #docs channel, which is also a good place to ask any questions about any of this. Thanks to @timkaye and @ElisabettaCarrara for helping with the process of converting our documentation content to Markdown.

There is more documentation about how this system works linked from the GitHub repository at https://github.com/ClassicPress/ClassicPress-docs.

Let me know your thoughts :slight_smile:

10 Likes

So, you first need to create a fork of ClassicPress-docs in your own GitHub account (which is an easy one-click). Once that is done, when you click that “Edit this page on GitHub” link it takes you straight to an editing page in your browser, with this message at the top of the page:

“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 simplycomputing/ClassicPress-docs, so you can send a pull request.”

Does the PR happen automatically from there as well, once you have made your changes?

EDIT. OK, that’s cool. I just made a change to the docs and submitted a PR. About the easiest thing I have ever done on GitHub. :smiley: It all happens in the browser - no need for command lines or GUIs.

6 Likes

What can we contribute?

3 Likes

I think if you just click the Edit link, then GitHub will create the fork for you behind the scenes (or prompt you to create one).

Does the PR happen automatically from there as well, once you have made your changes?

You should be prompted to create the PR after making a commit.

If you see something in the docs that is outdated, doesn’t make sense, or is duplicated, let us know via an issue on GitHub, or take a shot at fixing it via a pull request.

There’s also much more that we need to do here, such as creating a code reference, probably just for the things that we’ve changed from WordPress at first. So the invitation to contribute is open-ended!

5 Likes

There should be a menu on the Docs site, not just for the docs, but to get back to the main CP domain.

3 Likes

Both the docs homepage and the main site are already 1 click away on every page.

Still, a simple menu would be a good addition. The best place to track this as an issue and/or implement it is here: https://github.com/ClassicPress/site-docs

Also, the default menu for this site’s theme (Susty) is on a separate page (which we don’t currently link to). This is a bit unusual but I think it’s probably ok because the site is very fast. More info about that here: https://blog.jacklenox.com/2018/06/04/delivering-wordpress-in-7kb/

3 Likes