Docs Site - GitHub Plugin Usage

Continuing the discussion from Some Changes to be made to CP Site (main and forum) and related proposals


Maybe I’m missing something, but I always thought a web publishing software should use itself for its docs. Why have Git at all?
If there are problems with revisions and with editorial flow and drafting changes to be scheduled, (and there are!), then these should be addressed in the software. It improves when it’s used for real-world situations.

2 Likes

I think there is a misunderstanding regarding the Git integration. This allows the docs to be edited by anyone without having to give them direct access to the site.

I think when it comes to Github that anyone is a bit of a misnomer.

2 Likes

I have no idea why giving people access to the site is thought to be such a problem. That is what roles and permissions are for. And if it’s to provide version control, again CP automatically keeps versions by default. So the whole Github thing is unnecessary.

As you might have noticed, I have made this point about using CP to promote CP many times before. It’s interesting that those of us who take this view are now in the majority of those still around!

If a project won’t eat its own dog food, then who will?

1 Like

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 @smileBeda 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 :upside_down_face:

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 :slight_smile:

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).

@wadestriebel

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?