Some Changes to be made to CP Site (main and forum) and related proposals

Projects Documentation
1

I am planning few changes to the website and reorganisation.

Sharing here each point I plan to do, so @wadestriebel but of course anyone else too can baptise or object as required. Some of the changes I cannot do my self.

This I cannot do on my own:

  1. On the footer of https://forums.classicpress.net, it has a link to Committee. I can’t edit those links thus someone with rights please:
  1. I find the design of CP Site unappealing.
    The least we should do is remove the overhead. We have 3 things looking like a menu/header.
    We really need only one.
    Screenshot 2021-07-08 at 22.00.55
    Screenshot 2021-07-08 at 22.00.553584×552 200 KB

    This is true on all pages. I am aware that the section I propose to remove is the page title, but it suffices totally to put the page title as a h1 element without background in same container as the actual post.
    The menu should not be confused with the heading of content. The top bar (share and donate) should be as tiny as possible and stick, on scroll. The main menu should scroll away (as it does already). Do these change cost lot of work? Specially the color mix is somewhat hurting my eyes :smiley:
    And I just think it is about content, not about coloured headings. Perhaps I see this wrong.

This I can and will do on my own

  1. On About ClassicPress Our Mission & Vision | ClassicPress, I will remove the Management Committee section entirely.

  2. On the same page under the Our History section I will link to ClassicPress governance proposal explaining that the Management Committee was dissolved and also link to ClassicPress Organizational Structure, which explains some of the history.

  3. I will delete the section Committee Members on ClassicPress Governance | ClassicPress

  4. Edit the page ClassicPress Governance | ClassicPress to remove all references to “Committee” in the ClassicPress Rights and ClassicPress Responsibilities columns, if any.

This is a proposal I want to ask opinion about and wether I can go ahead with it, or not, and what the process of “review” would be:

  1. I propose at least biweekly blog posts on Welcome to the ClassicPress Blog. Topic is at minimum a summary of new plugins, new milestones achieved (freely gathered from any available) and other on-topic stuff. I will write those blogposts myself and partially deploy my army of writers for some of the research and copywriting.
    I propose topics in a broad range of “Develop websites” if we miss any more on topic content temporarily (however the main focus shall be the “progress of CP and CP”
    I think this is also a good place to share financial reports, quarterly team reports, and the like.
    I also propose a new category “Built with CP” to introduce each post a new site built, or rebuilt, with CP. This can serve as a kind of showcase too.

  2. Given discussion slack CP main DOC will likely live in Git (to my frustration, because it means to play around with new tools).
    But it will eventually save some hustle in setting up a new sub-WP install.
    Note, that DOC section should not be editable other than (hopefully) in some form of “user contributed notes” because the doc itself will be generated from code docblocks.
    We would need the ability to enable “comments” on each page generated by that GIT driven doc.
    I will run the code doc sniffer over a CP install and generate all related posts, then we need to replace all links pointing to doc site of CP, and then we need to convert all that to MD format for git.
    I am truly not sure this is the best idea, given the tools are there already to manage this on a CP CMS, but I will try.

Please let me all know your thoughts, I will be starting with this work over the coming weekend.

1 Like
2

Happy to do this, you may need to remind me this weekend if I forget!

All good, let’s just get it updated if you have time today or tomorrow. No need for a long discussion on it I don’t think :slight_smile:

Sound good to me, again I don’t think we need a long discussion, let’s just do it. I can get you (almost) any information, just ping me with what you need.

For 2: I don’t know what this means, I think I am just tired and not understanding but let me know :slight_smile:

1 Like
3

OK all cool then.
Notice that while you replied I added a point 2 to the “cannot do on my own”

About point 2 of the This is a proposal part - it’s about DOC, will need time, so we do not need any decision or “ok” today. We can discuss this thru time, as long we do not “procrastinate” it too much :wink:
Perhaps it will be better we quickly chat this out in slack one day. Or meet in call, is actually much more effective.

1 Like
4

Sounds good!

Re the 2 for cannot do, lets loop that into a chat re the doc site too :+1:

And thank you for taking this on :slight_smile:

1 Like
5

Maybe I misunderstood “documentation living on GitHub”, but simply it’s not possible to add comments on a GitHub files but only to PRs, commits or issues.

1 Like
6

You didn’t misunderstand
Current doc is stored on Git.

However, code documentation like this one get_sites() | Function | WordPress Developer Resources is generated by code from code comments, not by humans.
And it would be plain silly if we where to document CP code manually.

Right now, we can use WP DOC, but in about a few releases hopefully we will have our own functions and features.
At that point the least, we will need our own doc.

Such DOC does not allow for human edits (community wise) because it kind of defies to whole purpose of code generated doc. The only way for users to add additional useful information is to leave comments, or “user notes”. Thus my objection to Git - and also because it is an awful process to generate the code doc, and to convert it to MD.

Not having our own doc, even if it documents wp_code, is however also not an option I would say.
We need what @kevinhaig created a long time ago :slight_smile: but unfortunately that’s gone.

1 Like
7

I’m sure I’ve seen a comment, possibly from @joyously, that the WP tool for generating this is available.

8

I agree this is needed (I use it a lot), but the tools are available from WP. There is a plugin for the feedback section, and a custom post type for the “More Information” section that is added from the docs team.
What Kevin was doing: writing his own tools.

For best results, the same coding standard as WP should be used. But unfortunately, this is PHP only. I have often wanted a JS reference too.

1 Like
9

I looked earlier but couldn’t find them. Can you share links if you have them?

10

I think I did not explain that well.
I already have that plugin and setup. I do in fact document my own plugins with it.

That is not the problem, the problem is that it is made for a WP (or CP) site, not for Github.

1 Like
11

Wether Kevin was using his own tool or not (I think he used the exact same core code, which is phpdoc-parser), the result is 100% the same:
It is a WP (or CP) site with code generated doc and user added comments

And that is non-git-compatible.

:slight_smile:

I have the WP parser from Devhub – Make WordPress Documentation (the whole system, this is not just a plugin or one-code install) setup locally since months already. It takes a few hours to setup perfectly. @azurecurve FYI if you want to try, above link should include all necessary info.

Yes, this works only when following WPCS (Documentation AND code standards) are followed. Which WP and CS do, and as long we use WPCS, there’s no issue.

About JS, we could probably extend this, but it needs something else than phpdoc-parser
I think it is a great idea for a second stage, again putting CP into a “more evolved” light.
Thus I will research about this.

But first, we need to solve this problem with “Git driven doc”, which is great for user documentation but unreasonable for machine generated doc.

12

Nope I developed my own parser specifically for ClassicPress. I did not like the core one, as it missed many things.

I also built a custom scraper to incorporate the docs as they were at the time of 4.9. So all the user notes are there from that time.

Now I put the whole doc system up twice, and not much interest was expressed. There was also much discussion of using the GitHub Doc system. There was not one person interested in setting it up as the doc system for Classic Press. So I basically gave up.

Everybody has their own ideas on what the doc system should look like and do, and what tools and scripts should be used. So you usually have to fight through all that negativity to get anything done in open source. I’ve tried many times, this was the last effort I will make. Open source is just not for me.

Also of note, I am a self taught coder, so the scripts, while they work, don’t always follow best practices. Usually when someone looks at my code, they turn green ( and it’s not “Green with envy” ;). Then they start re-coding everything.

But I will tell you the entire doc system can be set up in about 2 hours. And maintained every time a release is made, in about 2 hours.

TBH I just wanted to help…but as usual … it did not work out.

I will however continue to code as I do love it :slight_smile:

13

Thanks for the info, @kevinhaig

As for “incorporate the docs as they were at the time of 4.9”, this should be possible to do with the WP scraper if we simply run it over a 4.9 (or better: ClassicPress) install.
What is trickier is the user notes, not sure how to get those.

I personally don’t care what tool we use. What cannot be is that due to “opinions”, we end up not having a doc.
And there is not much to opinate here actually. The Code Doc Blocks are there, and it is silly to not use them, thus, human written doc is not the way to go. This is just a fact. Also fact is, that converting a “WP/CP” post doc to Github is again a silly, unnecessary additional step.

If we simply take the formula for perfection, which is “As long you can take away something without breaking the functionality, it is not perfect”, we can exclude opinions and discussions.
The minimal, working version of such DOC is to let a machine scan the code and build doc from the Code Doc Blocks.
Everything else added to that, is not making it more perfect, but more bloated (and perhaps fancier).

I totally understand your frustration and understand your reasoning. I would prefer to not use a “wheel re-invented” solution, but on the other hand, if your system is able to do all what you described, I am interested in using it.
The main question here is, if you would be able, and willing to, share the source so I can build this for CP finally.
If you are, would you mind to share this with me?

I am a self thought dev as well, and I will not belittle you because of possible coding approaches because I did not forget where I started. I did not forget that I knew nothing about code a few years ago, and still know nothing, this is just my live style. You never learn out.

What is “bad code” can be rewritten and there is nothing bad with that. The credit goes to you as the initiator and the one with the will and persistence to actually create it rather than fuss around with opinions and discussions. Don’t misunderstand me, I am aware that a democracy lives on opinions and discussions, but if people die because the society is not agreeing on how to perform a surgery or respond to a cataclysm, we can as well go back into caves. Without going into politics, this is IMO one of the main reasons why democracy is not the final solution :slight_smile: - votes can be influenced, lobbied and in the end, it is just a ochlocracy. Specially when we vote but do not have constructive contributions to make. I am from a country that heavily suffers under this effect and ended up putting up laws that directly oppose Human rights just because “the majority voted yes”.

So, enough of this off-topic reasoning.

I don’t think there is much to discuss. The requirements are clear, we need a DOC. And it needs to be easy to maintain, and not go over 5 edges to achieve the goal we can achieve with one edge.
Thus, It is perfectly OK to have a GitHub stored user documentation with How To’s and the like, but for Code DOC, we will plain simple need a (plain simple) CP Install where we can manage these code docs

I am not sure if I miss something here but it shouldn’t take too much work to actually create such install, put it in a subdomain of CP, and Link to it. The current doc.cp.net (user doc) can still proceed existing. We can create a codex.cp.com or developer.cp.com for the code-doc

14

This I can and will do on my own

  1. Done
  2. Done
  3. Done
  4. Done
2 Likes
15

If there are tools which produce the required content, but which isn’t Git compatible, isn’t the solution to not use Git for it? This sounds like square peg, round hole problem; if the tools output html content, lets serve it through a site doing html…

2 Likes
16

Exactly! Just what I say. And for that we need a WP or CP driven install.
As said, we can still use Git for user doc, such as how to and whatnot. That is actually already running here and can stay http://docs.classicpress.net/

I already asked for a sub install but the objection was made that “we already have http://docs.classicpress.net/, which runs on git”.
This, is the only thing stopping me right now from finally getting up that DOC.

17

Breaking this element of the conversation into a thread of its own.

2 Likes
18

8 posts were split to a new topic: Docs Site - GitHub Plugin Usage

19

Most of the GitHub discussion is way off topic from this thread, so I have moved it to a new thread.

20

In terms of this thread, I think we are all good. Let’s schedule some time to chat about the outstanding bits, and continue the convo re the codex on that thread.