Contributing to the ClassicPress documentation

Projects Documentation
1

Our documentation site at https://docs.classicpress.net is now serving content based on the Markdown files stored at GitHub - ClassicPress/ClassicPress-docs: ClassicPress documentation content, 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:

And if youā€™re already familiar with using GitHub and git, you can fork and clone the GitHub - ClassicPress/ClassicPress-docs: ClassicPress documentation content repository as described in this tutorial.

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 our Slack group 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 GitHub - ClassicPress/ClassicPress-docs: ClassicPress documentation content.

Let me know your thoughts :slight_smile:

10 Likes
2

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
3

What can we contribute?

3 Likes
4

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
5

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
6

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: GitHub - ClassicPress/site-docs: Files for the site at docs.classicpress.net

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: Delivering WordPress in 7KB - Jack Lenox

3 Likes
7

I couldnā€™t help but notice that the DOC of CP is not presenting any ā€œDeveloping WITH ClassicPressā€ section yet.

That may make sense because right now its basically a WP 4.9 version, but, in future I assume CP will have its own specific methods and filters and so on.
Also, WP DOC is of course including all DOC for 4.9 above as well. Example, their DOC will include do_blocks() which is of course not available in CP

That might (specially on a future timescale) confuse users, and also be a tad annoying as the Developer or user has to check each time the @since tag, to be sure they donā€™t use a unsupported function

My proposal would be to use WPs documentation generator (GitHub - maheshwaghmare/phpdoc-parser: Documentation parser powering developer.wordpress.org) to generate CP specific doc. I already use that plugin/setup to successfully generate DOCs for my own plugins.
All that is needed is basically install CP and run the parser to generate all the DOCs. This will ensure that NO doc whatsoever not part of CP are logged

Of course since the DOC of CP lives in Git, the post types canā€™t be used as generated by the plugin, since those are intended for a WP website, rather than a Git Repo,however there can be different approaches to solve this like Migrating from Wordpress blog to GitHub Pages, or simply decide to create a ā€œrealā€ website for the CP Doc managed by CP itself.

What is the roadmap on this?
Creating each and every doc page manually in GIT will on the long run be unproductive - an automated process should be used I think. And as said as soon CP ā€œdivergesā€ from standard WP, a dedicated code doc would be required, I think.

Any input/plans on this?

3 Likes
8

Hi @anon66243189,

The biggest and best effort on docs has been done by @kevinhaig ā€“ link below. Iā€™m not sure if the content was a scrape of the WP docs, or if it was generated from ClassicPress source via PHPDoc, but, the latest article on the site has a bit of a roadmap. Note that itā€™s not an ā€œofficialā€ ClassicPress endeavor (which is why its not on an official domain); Kevin just recognized the need and took the initiative on it. Hope this helps.

ā€¦and welcome to the community! :slight_smile:

https://cpcodedocs.kevinsspace.ca/

2 Likes
9

Ah great! Thanks a lotā€¦ That is indeed what I had in mind.

Need to find where to contribute there since I found 2 typos on the landing page :stuck_out_tongue:

@kevinhaig - FIY on the homepage it says whick instead of which (perhaps a reference to John wick, I donā€™t know haha) in this sentence

ClassicPress Docs is a site for documention of the ClassicPress blogging system, whick was forked from WordPress in 2018.

And further down thereā€™s a double ii in initial, sentence

This is an intiial demo of the documentation system.

Also I see the '' are encoded to ā€˜ā€™, probably would need a look as well.

Can I help somehow? Let me know please!
While I can see a ā€œloginā€ form I canā€™t sign up, it seems.

This should definitely become part of the CP core.
As mentioned elsewhere, most of the people I talked to, are (amongst other things) scared because the DOC in the official page is almost non-existent.

4 Likes
10

Hi there.

Yes I am working on a code documentation system. I am currently working on an update that will improve search and grouping of docs. Once this update is ready I will change the GIT repo to public and let folks take a look.

I developed my own Core scraper for this for a couple of reasons. I did not really like how the content areas were set up in the WP parser, and I wanted to be able to add the docs from the August 2018 Codex to a section in these docs.

The system I set up adds the scraped content in the content area of the CPT. The August 2018 Codex content is added to a post meta item, as are the Uses and Usedby tables. Everything on the Class, Method, Function, and Hook items are available in the editor, should adjustments be required.

The system needs to be manually set up in a localhost environment and then parts of it are uploaded to the site for implementation. Every time an update is made to core, manual adjustment to the core docs would take roughly 1/2 day. So not ideal, because it is not an auto update system. But after becoming quite familiar with the varied quality of the code and docs in core, I remain concerned that an auto update system will ever work.

Now this site at the moment is just for demo purposes, and Iā€™m not really sure that the board at ClassicPress will accept it. I am a self taught procedural coder, so I am doubtful the code quality will meet acceptable standards, but we will see :slight_smile:

Thanks for the notes on the typosā€¦should be fixed now.

4 Likes
11

We need to merge the content at docs.classicpress.net (which is stored in GitHub but is actually managed using a full ClassicPress site that pulls updates in from GitHub) with the newer site at https://cpcodedocs.kevinsspace.ca/. Having multiple types of content that are generated in different ways is not a problem.

This is the main problem I see with the code docs site as it is now. It is a good starting point and a good thing to have, but we have to automate this - it is not sustainable for updating the documentation to take longer than all the other steps of a new release put together.

This sounds like a good next step with this project.

12

The update is taking a bit longer then I thought, the auto complete search of potentially 9000 items is a bit tricky to say the least.

The manual update process is not so bad, Iā€™ve probably overestimated the time, and it would only be for one person.

In any event I will look at ways to make it update easier.

2 Likes
13

We now have a full documentation at http://docs.classicpress.net/

Human written content is in progress, while Code Reference is machine generated.

I guess we can close this thread as solved after almost 2 years :partying_face:

Also contributing to the DOC has changed, see Currently Active Projects - #7 for further and current information

1 Like
14

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.