Creating a ClassicPress Codex

Splitting from this discussion:

I know this discussion has come up a few times and not made much progress, but we currently have people actively willing to help create a ClassicPress Codex/Developer handbook and think we need to get a decision made and some progress made.

I know there is a Docs site on GitHub, but the tools available to automatically generate a Codex produce HTML output and, to take take advantage of these tools, we should be looking at a ClassicPress site on a subdomain which will allow us to use those tools to automate the process rather than trying to reinvent the wheel.

I reference the WordPress Codex quite a bit, but as it will be diverging from ClassicPress with the new functions and so on created for blocks. we need one based off the ClassicPress codebase.

We can get this done fairly quickly using existing tools if we go with a subdomain site; if we have to create tools to generate Git compatible markdown it will take a long time and (possibly/probably) never actually happen.

2 Likes

Just to clarify:
Git powered Docs can stay, those are user docs (where we write text that cannot be generated by a machine)

What we need a CP install for, is the codex (Code generated doc for Code).

I already pushed some changes to the user doc that would reflect all the necessary changes to GitHub.
What would be needed now is a WP or CP install on a server, which we can then point to something like codex.classicpress.net

We will then link to that from doc.classicpress.net


Edit a bit later:
I think GitHub Doc is a horrible idea.
It is awful to create good looking doc. It has no search features for the end user on the actual site, it has no possibility to show off CP as an actual site, it has no normal PHP or CSS/HTML features like any other CP site has, that we all could use if the doc would be stored in a normal website driven by CP.

Yes, it will need users to have special permits to edit them, but that is no difference at all in GIT.
You can make as much edits you want in Git, at the end, you need a “senior” to accept your changes, and that means plain and simple duplicate work. Plus, it needs more work to even create a simple menu or search form. Additionally people need to do things like “fork” and “commit” and “Merge request”. No one knows what that is when they simply deal with writing versus coders.
I don’t think this is a productive solution.

1 Like

GitHub for me is for source control; ClassicPress is for content.

2 Likes

I think it should be made clear that there is function explanations and there is system explanations. The functions part is generated from the code (PHP now, hopefully JS later), and the system part is what a doc person writes about the APIs and various things like hooks.
It makes sense to keep these separate, so just having a docs subdomain is great as long as it has subfolders for user, PHP reference, JS reference, and system information.

1 Like

This sounds like you mean more than the user contributed notes. Do you have an example showing what you mean?

Click on https://developer.wordpress.org/reference/ and look at all the links in the API box on the right.

OK, so the “fluffy” part of the developer handbook (as my boss might describe it) surrounding the codex.

1 Like

I think the term Codex is confusing. It was WP’s wiki, a mixture of code reference and system explanation, with user content all through it.
It has been mostly migrated to separate areas for User docs, Code Reference, and API handbooks, with moderated user comments.
We are copying the separated parts, so referring to Codex is a break in communication, unless you really mean the old WP Codex.

See the docs site: https://docs.classicpress.net/

It is being called “Code Reference”.

Yes, on the site it is Code Reference, as it should be. I was referring to the conversations here and on Slack, though.

I refer to codex just because I’m used to the name from WP. I’ll try to use coderef from now on to be more accurate for CP.

1 Like

We have the new docs site live with some tweaks still to make, so this discussion is closed. Issues or requests for the doc site should be in new threads.

2 Likes