Proper content type and "categorisation"

There is a slight issue, which was already existing in the previous doc: content categorisation.

It is very clear what https://docs.classicpress.net/code-reference/ will/does hold:
Everything related to Code!

It is also very clear what https://docs.classicpress.net/plugin-guidelines/ will/does hold:
Everything related to Plugins!

Now, https://docs.classicpress.net/user-guides/, is less clear.
IMO, this should hold only guides for users.
Stuff like this (previously in the “Use ClassicPress” section) should not appear in a User Guide:
https://docs.classicpress.net/user-guides/developing-classicpress/
https://docs.classicpress.net/user-guides/installing-with-composer/
https://docs.classicpress.net/user-guides/testing-classicpress/
https://docs.classicpress.net/user-guides/testing-classicpress-scenarios/
https://docs.classicpress.net/user-guides/security-page/

Those are Developer oriented IMO (and even, contributor oriented) details.


However, all Developers also use ClassicPress and thus are actual users. Just as well, a user might develop with ClassicPress.
What surely neither of the 2 groups do, is develop ClassicPress itself, those are contributors.

Thus, I am just not sure, if we should keep it as is (everything not Plugin, Theme or Code related, goes into User Guides, unless it is a contribution related thing, such as testing CP, developing CP, etc).
We can of course group the user guides into “Developer” and “Consumer” or whatever taxonomies.

The question is crucial because if we change it, we do have to change it now, or never
This because @James (and whoever is contributing actual code) sometimes links to these pages.
The links are now already broken because someone (Beda) changed them :slight_smile:
Thus, we need to fix this up once and for all, this means, none of the links can change later anymore.

That is why I want community consensus on this, before I send James the updated list of redirects to do.

The big question thus:
Add a new CPT “Developer Guides” (which then will hold whatever is not a end user guide and produce a new permalink trunk developer-guides/), or, keep current User Guide and create taxonomies therein, which will not influence the permalink.

For simplicity obviously keeping user guides is easier, but I bet, this will be complained in future as “messy” (even if we include taxonomies to filter, it might confuse the one or other user).

2 Likes

I am good with developer guides, similar to Shopify’s .dev domain specifically for developers.

2 Likes

Like @wadestriebel, I think it sounds reasonable to have a separate developer guides to user guides; an end-user may be put off if they look in user guides and see dev resoiurces.

2 Likes

8 posts were split to a new topic: Ordering of guides on doc site

Yeah, that is what I also prefer at first glance

however, it pulls up another issue.
What is developer? What is contributor?

Because if we separate “User” guide and developer guide we can say that a “Update CP” is a user guide, we can say a “Security page” is a developer guide… but what with “Testing CP”?

So I went back to … just throw everything in the same pot (user, developer and contributors), and instead of making them CPTs, make them Taxonomies, which does not change the URL, and we can still separate them in lists if needed

This is separated - I have replied to you in regard of this in Slack, we can then move to a new topic about it.
It clearly needs work :slight_smile:

If going with “User Guides” we should build in the types from the start to allow separation of more technical content for devs

Yes exactly, that’s why I want to determine this now

I am split between both solutions. :expressionless:

I think docs like that are always tough when you are trying to support both end users and devs.

My two cents, I think anything that is a feature should be on the user-guides where as anything that requires code changes should be on developer-guides.

Perfect example, security page should be broken into 2 docs. The api info etc should be a dev doc, the contacting authors should be a user guide.

2 Likes

They can always be cross linked where appropriate

That makes perfect sense

Where would we put that category which is “Develop FOR CP” and “Test” and the like?
Thus, things that both users and devs can do

contributor-guides?

I don’t think “end-users” would be looking to test ClassicPress so that would be a dev guide.

1 Like

The main problem I have with this is, if we make a mistake, we have to change post type, and thus URL
If we use taxonomy, then we just change the term, and that does not affect the url.

Ok so this points towards 3 CPTs.
This means we will have to be more careful with actual content publication and specially with hardcoding urls in code, posts, or else.

I will have to wait for James to add the new CPTs code, thus we still have some time to chat here :stuck_out_tongue:

3?

User, dev and contributor?

yes
(additional characters for satisfying discord)

In the WP world, the Codex was a mixture of user and dev and contributor. It’s a mess, and was separated into user docs being under the support section (they are still working on categorization), the code moved to the Code Reference and each API has its own section, and the contributor stuff is separated into a handbook for each team which is linked from that team’s blog. The team blogs hold discussions, agendas, meeting notes, and announcements. The problem comes in when the developer notes and release field guides are the only place to find details because the actual docs don’t get updated.

I once proposed to the WP docs team to organize the user docs like the admin menu. Of course, not every topic is on the menu, but you can add more like Installation, Hardening, and Troubleshooting.
I suppose the developer docs could be organized the same way, but should be distinctly separate from user docs. Consider what will be returned on a search when you think of whether they should be together or not.

To add my 2 cents. Having 3 types of guides is a good way to break down the content: user guides (for anything related to managing and maintaining CP websites), developer guides (for anything related to plugin/theme development, etc.), and contributor guides (for anything related to CP core, websites, and other assets/projects).

1 Like

OK, I think we have consensus

@James objected that Contributor Guides should stay/be on Git.

For now, we are adding a third CPT for Developer Guides, which will allow us to at least move things like the security page docs out of user guides.

2 Likes

User guides and developer guides are now live as 2 separate sections (with redirects from the old URLs to the new ones).

Contribution documentation is already on GitHub: https://github.com/ClassicPress/ClassicPress/blob/58e8de240141f6d7a3c8d0131db591076f6d7374/.github/CONTRIBUTING.md

This is the standard and expected place to find contribution instructions for projects that are managed on GitHub. For example, GitHub will automatically show new contributors this file because it uses the standard name. Also, this content is fairly routinely edited by contributors that don’t currently have access to the docs site, again using GitHub.

If one day we end up having more contribution guides for things that aren’t just the core software then they could be placed into a new CPT. This would need to be done with a clear idea of what already exists (there is more information than just that contributing.md file on GitHub) and a plan to organize the new and old content together reasonably without breaking links etc.