Proposal: Simplify documentation permalink structure

[viktorix]

Before I outline the proposed permalink structure, I will note that any URL changes will include redirects. So no old URLs will go to the 404 error page.

Right now we have permalinks such as:

https://docs.classicpress.net/user-guides/using-classicpress/posts-screen/
https://docs.classicpress.net/user-guides/debugging-in-classicpress/
https://docs.classicpress.net/developer-guides/installing-with-composer/
https://docs.classicpress.net/plugin-guidelines/plugin-directory-submission-guidelines/

Code reference permalinks are fine, won't be touched:
https://docs.classicpress.net/reference/functions/__autoload/

Proposed structure:

In addition to a long, complex structure, the CPTs are treated as pages. So the parent dropdown is getting longer and longer.

Proposed change 1: Switch CPTs to post type, no need for parents.

Now, once they don't have parents to be part of the URL we would simply that part.

Proposed change 2: Simplify user guides and developer guides permalinks:
https://docs.classicpress.net/user/posts-screen/
https://docs.classicpress.net/developer/installing-with-composer/

Lastly, right now we have plugin guidelines CPT. But we will be adding themes and snippets soon, which would require their own CPTs.

Proposal change 3: Change plugin guidelines CPT to "guidelines" and keep them with page capabilities, so we can use the parent page for each type of guideline:
https://docs.classicpress.net/guidelines/plugins/directory-submission-guidelines/
https://docs.classicpress.net/guidelines/themes/directory-submission-guidelines/
https://docs.classicpress.net/guidelines/snippets/directory-submission-guidelines/

---

One additional note. Currently, parent/child relationship is used to automatically display a list of child pages on the parent page. We can either do this manually once changes are made or use the object relationship plugin to create necessary associations for a shortcode to display associated posts.

Feedback and suggestions are welcome.

[KTS915]

Proposed change 1: Switch CPTs to post type, no need for parents.

I presume you mean "switch to non-hierarchical post type". If they are already CPTs but hierarchical, this is a simple fix, and I agree that this is the right way to go.

Agreed on 2 too.

I am unclear about 3. Why does there need to be an intermediate plugins/themes/snippets URI fragment between guidelines/ and the submission guidelines? Why can't we just have, for example https://docs.classicpress.net/guidelines/plugins-submission-guidelines/? How many "guidelines" are there going to be in total? If just these three, why can't they simply be regular pages (and thus eliminate the need for a CPT altogether)?

[joyously]

I don't see much change from existing to the proposed, except that you dropped the -guides portion of the top level (which I wondered about when it was done).
As for the code reference, it is only PHP, and there is nothing for JS or even CSS, so I'm not sure where those would go if anyone chose to work on it.

1. I was going to say the same as Tim about the CPT. (Why is there a CPT?) But it seems like these things are related in a hierarchy way, so pages do seem appropriate. Otherwise, you'll have to make categories and the way those are sorted by default is date, so it makes a mess of navigation. The trick is to limit the depth.
2. Yes, remove the extra -guides.
3. I don't like the guidelines part. Should there be a section for contributor since we have user and developer? That section could have team handbooks, submission guidelines (requirements), tutorial for setting up a dev environment. At the same time, a code contributor would be a developer, so, like WP, a plugin handbook and a theme handbook logically go under developer, and at the end of that handbook is the submission guidelines.

[viktorix]

I can't answer the "why" since I didn't set this up. I can only assume they wanted to keep things separate and utilize permalinks structure. Everything has CPTs and uses hierarchical page capabilities. The parent dropdown is getting long and we barely started migrating the content. It'll get very long quickly.

There are a lot of WP handbooks, and they appear to use hierarchical CPTs. If we want to copy WP, we can try to go for the same setup. My problem with it is longer URLs usually are not great for SEO. Shorter, more concise URLs correlate with higher rankings. I'm also not seeing any benefits in having hierarchical URLs.

I also see WP's handbook menu uses nav menus, so they are manually controlling the order.

So one possible developer/handbook setup could be:

• Use Developer Guides hierarchical CPT
• Create a page for each handbook, for example: Theme Handbook
• Each new page of the handbook would be use the main theme handbook page as a parent page.
• The permalink structure would be: /developer/theme-handbook/page-title-slug
• Use nav menus to create a ToC for each handbook

Another option, which I might prefer simply for organization and ease of use:

• Create non-hierarchical CPT for each handbook, for example: Theme Handbook
• Having one CPT per handbook allows for easier management of content since we can easily see all the pages for a specific handbook without all pages from all handbooks being dumped in one place
• Don't have to worry about specifying parent page.
• The permalink structure would be: /theme-handbook/page-title-slug OR /theme/page-title-slug
• Use nav menus to create a ToC for each handbook

The second option offers the most flexibility and ease of management.

If we break everything down into handbooks, we probably wouldn't need "Developer Guides" CPT.

And come to think of it, maybe we should rename User Guides to something a bit more meaningful to users such as "How-Tos" or "Learn" or something along those lines. And maybe change permalink to "/learn/editings-wp-config".

WordPress has both video tutorials under "Learn" and how-tos under support articles.

Thoughts?

[KTS915]

I don't see any reason to use hierarchical CPTs. So I'm essentially on board with your second set of proposals, though I think you should give some thought to using a custom taxonomy for each CPT.

You could the use the taxonomy terms as essentially providing chapters in each handbook. Then, with a little more code, you could create a nice ToC automatically without needing nav menus.

[viktorix]

If we were to use taxonomy for chapters, then we would have to use post attributes ordering with menu_order to display them in a specific order.

If I see this right, these are the following handbooks:

• https://developer.wordpress.org/coding-standards/
• https://developer.wordpress.org/apis/
• https://developer.wordpress.org/themes/
• https://developer.wordpress.org/plugins/
• https://developer.wordpress.org/rest-api/

core contributing:
https://make.wordpress.org/core/handbook/

and docs:
https://make.wordpress.org/docs/handbook/

[KTS915]

That's the easiest way, certainly, but it's not the only way. You could even not bother with code and use a plugin to create the order by drag and drop.

[KTS915]

Looking at those links, there's really not much there. Are you sure you can't do it all with just regular posts and categories (no CPTs or custom taxonomies at all)?

[joyously]

I've heard it mentioned that WP uses a Handbook plugin. I don't know what it does, but probably create a CPT and make the navigation. The ToC is a separate plugin.

The original codex was everything all thrown together. I found it difficult to find dev stuff there, so I liked it when they made the code reference and moved the explanations onto the appropriate pages. When Beda made the CP code reference, he didn't copy the explanations or user comments so it's not as useful.
WP docs team is still working on the categorization of the user support articles. Right now, they are all together and you can't read it like a lesson or book or tutorial. It's just whatever they choose to highlight on the main page, otherwise you have to search, but you have to know some keywords to search. I think for user docs, it's important to structure the information so they can find it again and/or keep track of their place in learning. This is why I suggested organizing by the admin menu. For the developer stuff, it's harder to impose an order. I do like the way that developer.wordpress.org shows all the developer docs under that subdomain, but our code reference ended up separate from the other dev docs.

[KTS915]

There's nothing to stop us adding comments and examples to the CP code reference. Beda was concerned that so many examples are wrong or misleading, so wanted them curated before being published. That seemed faur enough to me.

[joyously]

Yes, I know, I was simply pointing out that we copied the reference part and not the docs part of it, and that reference is mostly for developers. Especially on something like WP_Query, we really need the docs part. But hopefully someday we would document the JS code as well, and then where would it go if PHP is https://docs.classicpress.net/reference/

[viktorix]

@joyously

WP docs team is still working on the categorization of the user support articles.

This is why I want to keep categorizations out of permalinks. Users don't care about URLs. They will follow what we provide on a page. So it will be important to create a "getting started" or "Beginner's Guide" page where we list all categories and link to all the necessary articles. I think your suggestion of using the menu for categories is good. That can help users find things quickly.

I think we could use built-in Posts for User Guides with built-in categories for the menu, then figure out a way to manually order posts within the categories. To keep things simple, possibly use Category Order and Taxonomy Terms Order plugin.

---

not the docs part of it

Are you referring to developer articles in the handbooks here? I just want to be sure.

---

For JS reference, is this the WP version you're referring to?
https://codex.wordpress.org/Javascript_Reference

---

Lastly, for the code reference explanations - should we add an option for users to submit them, just like WP? This is separate from the permalinks, so I will create a separate issue if that's the case.

[KTS915]

+1 for using built-in posts and categories. I also think it's a good idea to invite code explanations (presumably using built-in comments), but we should review each one before approving it.

[viktorix]

Yes, I agree with using comments for that and moderating them. I've created an issue for this in the docs site repo.

[joyously]

not the docs part of it

Are you referring to developer articles in the handbooks here?

The WP code reference has 3 parts: code is parsed for pages, each page might have More Information section which is not affected by the code parsing, each page has comments with up/down votes. WP docs team migrated explanations and code examples from codex to code reference. Beda copied the code that does the parsing, so CP has the main pages, but not the explanations or comments. The main one needed is WP_Query but a lot of functions have More Information that is very useful.

For JS reference, is this the WP version you're referring to?

No, they don't have a JS reference either, and the only thing on CSS classes is a small section in the Theme Handbook (although they might have more these days in the Block handbook, but I've never read it). I'm referring to parsing the JS and being able to search for functions like the PHP code reference.

[viktorix]

It appears that everything is already built-in, just not used:

Here's an example with an explanation added:

Would need to figure out how code highlighter works. Maybe use shortcodes for that. Need to add ToC, and make notes show up in the frontend.

[joyously]

I think those details about the code reference are tangential to this issue of doc permalink structure.
My point was that the code reference can contain a lot of developer docs, and having it at a totally different endpoint is confusing and doesn't leave room for a JS reference either.

[viktorix]

After giving it some thought, here's what I think will work based on the feedback in this thread:

Code reference:

• docs.classicpress.net/reference/php/functions/__autoload/
• this allows for JavaScript reference in the future.
• @joyously does this work for you?

For developers:

• docs.classicpress.net/dev/plugins/what-is-a-plugin
• docs.classicpress.net/dev/themes/what-is-a-theme

For users:

• docs.classicpress.net/article/using-permalinks
• This will be regular posts, then using categories/tags to create pages specific to certain types of usage such as "Basic Usage".

Core contributions will be linked to GitHub instructions.

[joyously]

This is better than before.
I can understand that you want to keep user and developer separate, but "article" doesn't help SEO or users.
What kind of search do you foresee? One search that covers the docs subdomain, or separate ones for the separate sections, or both?

[viktorix]

Ideally, having a faceted search for the entire documentation site would be best. I don't know how that will look or how we will implement it. We'll start with the main search, and then tweak it as needed.

I don't want URLs tied to specific categories for users so they can be grouped as needed manually, be it a category, tag, or manually on a page. Having a category in the URL for SEO benefit is none. Here's Google saying it. The content on the page will be much more important.

Other options that could work:

• docs.classicpress.net/user/using-permalinks
• docs.classicpress.net/how-to/using-permalinks
• docs.classicpress.net/learn/using-permalinks

If we tie URLs to a category, then we need to figure out what categories to create. If we decide to change category later then the URL will change too. So it's not

[joyously]

I agree that the category should not be in the URL, but your proposal didn't suggest that (and I didn't either).
I just think that "article" is useless, although I can see that it could be a CPT name.
There are some topics that are marginal between "dev" and "user".
If you aren't using a multisite with folders, it will be one big search, which is not that great for finding just user or dev docs. If it's multisite, the search is just that site, and then it's a problem to search across all the docs... WP uses a Google custom search for this, and it's mediocre.

[viktorix]

This is not a multisite setup, only a single instance with CPTs. For users, I want to use posts (not CPTs). So instead of article it could be nothing. But, article is a common slug for articles in knowledgebases.

• Intercome KB example: https://support.wishpond.com/en/articles/3497604-how-to-organize-your-wishpond-dashboard
• Zendesk KB example: https://support.dashlane.com/hc/en-us/articles/115005432325-Get-started-with-the-Dashlane-web-app

If we leave a slug out, it could just be:

• https://docs.classicpress.net/debugging-in-classicpress/

Looking over our current docs for developers, they are not specific to themes/plugins. They are core/API articles. I was thinking if we can, we could use URL without theme/plugin slug for those:

• https://docs.classicpress.net/dev/classicpress-directory-api/

[joyously]

This is not a multisite setup

Maybe you should consider this decision carefully. When I search for a function name in the code reference, I don't want to see user articles that might mention it.
The code reference search works well now because it is by itself. It might ought to be its own instance under that folder, which can be done as a separate site or as a subsite.

Despite other sites using it, I don't think we need "article".
There are missing docs still, like theme and plugin handbooks, and all the various APIs.
Again, it's not just about the URL structure, but what gets searched for each part of the docs.

[viktorix]

I'm not sure how/if phpdoc-parser plugin works with multisite, since there are multiple sites and multiple tables. But we should be able to limit searches based on CPTs using a single instance. Managing multisite right now isn't something we have resources for. If the need arises, we'll tackle it later.

• /dev/plugin/ and /dev/theme/ would be the handbooks. There's no other content we can put there.

Maybe for users, instead of article a more appropriate slug would be learn. It will have basic how-to/beginner content, so learn might be appropriate. This category is the one we're focusing on since we link to articles from the core.

Ideally, we will offload search to something better like ElasticSearch. But we don't have the resources for that. So for now, we will use built-in search, split up search results based on CPTs, and make sure code reference has its own search. I'm not worried about search for now because we barely have anything to search and code reference is searchable. So search will be tackled a bit later.

[viktorix]

Refer to #36 for implementation.