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
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 
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. 
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 
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.
This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.