My point exactly!
I have to be honest, I don’t understand. It is CP running with a plugin that pulls markdown from the GitHub repo?
- Editing a doc on GitHub takes more time
- Is less efficient
- Even just editing a link will make a cascading event almost impossible to handle
- Styling and writing is awful, and it looks awful
- No search features on the site
- No breadcrumbs
- editing a “menu” took me editing an entire repo due to no link updates
- Current doc GitHub has I believe a total of 4 contributors. I dare to bet one of the reasons is things like “fork”, “push”, “pull”. Unnecessary and totally alien tech talk to some writer of a doc. No one does nor will contribute to that unless they are real deep developers, who shouldn’t write or maintain doc anyway.
- Not the ideal and made for interface for a content management.
- CP and WP are the ideal tool for this
- Finally, and this is major: code doc will be created by a machine into HTML wp(cp) posts. Do you really want to go and convert, upload, and update over 8k single posts with links to each other on github, along with just as many user docs (in future)?
My last PR to GitHub doc showed how much trouble it is to even update a doc where 30% of the links currently are dead, even if on GitHub they actually lead to content (but on live site lead to empty “coming soon” page). I’m not going to manage 8k posts with raw HTML and zero visual editing, and what’s really really worse, without permalink feature that wp has.
Since 3 years I believe cp exists and the doc still says “coming soon” in some parts.
I don’t understand why we don’t listen to the community, which is overwhelmingly in favour of the simple versus the weird complex solution.
No offense, I love GitHub and open editing, but it is not made for this goal/task and is just an awful “solution” to this problem we face: there’s no doc for cp.
I can setup a full fledged doc directory with search and front end forms and access control and design in less than 2 days. Over a weekend basically.
All I need is a network cp instance with admin access.
Give the community the chance to fix this, because this is what it needs, it’s not “to be implemented” as it is already partially there but truly broken and awful both in editing and visual experience.
Again, no offense intended and no preference pushed, I’d love to use open and public GitHub for this, but it clearly doesn’t work as we mean it to.
1 Like
I agree with everything that @anon66243189 said. And I’ll add another. The final output is going to be HTML. So why can’t I just write in HTML, without any need for backticks or other such fluff? As I’ve said before, that is also the only way to guarantee to output properly semantic HTML.
This isn’t quite accurate, we had direct access and no one edited them ever. The GitHub version is a copy of what was there and was originally added due to the community asking for it, Contributing to ClassicPress docs. Additionally, you have admin access to the docs site, you are welcome to update things there as you see fit.
I knew there was a discussion somewhere, I found more info here: Contributing to the ClassicPress documentation
Also going to add, I am happy to make the change back, but it is low on my priority. If we change back to the “vanilla way” I would want it to stay that way for the foreseeable future. I just don’t want to get into the game of changing the way the docs are managed every 6 months when new community members join, that is my biggest hesitation to changing things.
@wadestriebel - in none of those posts I see an actual ask if the community to use git, but i see a “this is an experiment”. I can see there’s a reference to “slack chat” which is not exactly mentioning a “asked by community” but “hope to have more contributions”. Did that happen? I don’t see that happened.
IMO, experiment failed and it didn’t address any of the problems I’ve mentioned in this thread above.
And I see here at least the active community members all seem to be not happy with this experiment 
Doc will never be a highly contributed part I think. But as said, if we need it, within the shortest time I can add safe front end edit modes and they can even save to drafts, if we are concerned about defacing and data loss.
I’m willing to add each and every user who wants to edit personally to the user base. I am 99% sure they’ll be probably one user max monthly asking for that.
Given the current situation since cp aurora we have 4 contributing to the doc 
That’s no reason to make it “easier for everyone” when it really, really isn’t!
I’m just reflecting what I as relatively seasoned git user sees and what everyone else in this discussion said
I don’t need any help in this. What id need is a site, with cp. thus if current doc is cp and I’ve admin rights there - I will make things happen.
But it’ll mean it’s not pulling anymore git stuff. Which doesn’t happen anyway as far I can see - at least not in a reliable way. Otherwise we wouldn’t have dead links in the doc.
I have the Time and the resources to get serious on this project. And I can confirm I already got active offers of help.
And I agree. It won’t change in future. It’ll stay. And it’ll be a perfect showcase
I am not sure what this means, the GitHub changes are only pulled in once the PR is merged.
Sounds great, green light from me to do whatever you need to 
You need to use a plugin (or fix core!) so that the original is not unpublished when a draft of changes is saved. This happened a lot over at WP until they finally put a plugin to handle it.
1 Like
Agreed. In fact, the proposal was made on this basis:
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.
So it previously “worked well” and now it doesn’t. The experiment failed. And if there’s an issue with having several people working on the docs, we should learn how to manage that with the tools that CP puts at our disposal (plus, if necessary, a plugin like User Role Editor).
1 Like
You do have to be careful about plugins on the official site, since the updates could be a security issue.
Of course. But the one I suggested, for example, is of very long-standing and I use it on almost every site I manage (including on sites where there are many contributors).
Additionally, you have admin access to the docs site, you are welcome to update things there as you see fit.
While I indeed have access, no page can be edited, it misses the editor and says “Edit on Github”
I am not sure how that is loaded, since neither theme nor plugins used on the site feature any code for that.
To have any chance to edit these pages we’d need this GitHub bridge disabled. How do I do that?
Ok wait, I stand corrected.
The theme does include code for that, in the template files.
Thus I think theme switch will do the job.
I will put the site under maintenance mode once I am doing real changes.
I have the DOC source material ready.
The DOC itself is created from code taken from CP directly and thus open source. No issue.
There are comments on each DOC when the DOC exists as well in WP, example:
I can import all those comments (whatever existed up and until WP 4.9) into our own DOC as well.
However, of course, I can’t import the users who authored them because those are WP Users, not CP Users.
Thus, if I import, it will be a comment added by Contributed by — 23 seconds ago — Edit
See screenshot of my local:
Legally this is no issue, as all those comments are GNU Free Documentation License v1.3 - GNU Project - Free Software Foundation, but, it might be not nice. Thus I will wait with them, since I can import the comments at any given moment also after creating the main doc, there is no requirement to do so during the main import or “asap” at all.
The question you’ve asked does not have a definitive answer, unless someone can find a policy on wordpress.org that makes clear the legal basis on which comments are made. But I can’t find such a document, so my current analysis is as follows.
First, the person making any such comment owns the copyright to the comment. (No document on wordpress.org could change that.) But as they don’t leave these comments in private, it is clear that they are intended for public consumption, and so wordpress.org has a license to keep and display them on its site. (This is essentially how the law views any comments on any publicly-visible website.)
If wordpress.org had expressly adopted a specific license, such as a Creative Commons license, then we would know the extent of the license granted by each person who leaves a comment. In the absence of such an express license, we are left trying to figure out the precise extent of that implied license, and that’s where things get murky.
This has never been tested in court, and it’s hard to be sure what should be implied. But I think there are probably three possibilities.
One is that the license has been granted solely to wordpress.org. If this were true, then copying and displaying such comments on a ClassicPress site would break the terms of the license. I don’t think that this interpretation makes much sense, however, for comments left on wordpress.org. Unlike comments on a blog, those comments are not really being made for the benefit of wordpress.org; they are being made for users of the code being commented on. Indeed, there are — and have been for years — several services that scrape both code and comments from wordpress.org, and this interpretation would render them all illegal. And, of course, the code is open source. So I strongly doubt that this interpretation is correct.
At the other end of the spectrum, it might be said that because the code itself is open source and licensed under the GPL, then so are all the comments. But I don’t think this interpretation would fly either. There is a big difference between code and comments — they are literally written in different languages — so I think this interpretation involves a logical fallacy. Most importantly, the GPL allows code to be used for profit, whereas I think it’s highly doubtful that most contributors of comments would be happy to see their comments sold for profit.
Having eliminated the other options, it follows that’s what’s left is the most appropriate approach. This focuses on the purpose for which the comments are made, which is clearly to enable the code to be better used and understood. So, in my view, provided that purpose is maintained, and provided also that the comments are not used as part of something that is used for commercial gain, then we should be free to have the comments on a ClassicPress site if we also include attribution to the original commenter.
You say that you can’t do that, but actually that’s not true. Those who comment leave a username, which is hyperlinked to an account on wordpress.org. We just need to keep those usernames and hyperlinks in place.
5 Likes
Tanks a lot for this insight
I found they publish those comments under GNU Free Documentation License v1.3 - GNU Project - Free Software Foundation and it seems as far I am able to understand it’s ok to use them
However I have as of now only a dump of the comments without user attribution
Thus I’ll wait with adding them and try to get either a dump or a scrape with attribution
I think then we’d be safe.
As it’s not an elemental part of the doc (many comments are simply very old) and with current doc status we only gain quality by adding even the tiniest part it’s also not mandatory to have them in the first “run”, I think.
I can always import them later since luckily they’re native comments.
Thanks again!!
Where have you found that? The GPL would certainly apply to comments included within the code. But, unless there’s some statement somewhere on wordpress.org that specifically refers to comments left on the site, then the GPL would not be relevant. (In fact, if there is such a statement but it can’t easily be found, it won’t apply either.)
1 Like
On their codex comments form at the bottom
If you log in and see the comment form, it’s just under it:
- NOTE: All contributions are licensed under GFDL and are moderated before appearing on the site.
1 Like