ClassicPress Documentation Hub
Announcing the ClassicPress Documentation Hub
We’re excited to announce the ClassicPress Documentation Hub is finally alive and kicking!
Many of you probably have visited the previous documentation a few times and then stopped doing so because there was not much information to be used.
One of the major problems was that someone Developing with ClassicPress needed to rely upon and fall back to the WordPress documentation, which has evolved a lot since WordPress 4.9 and often includes references and details that are irrelevant for ClassicPress.
Just check all the functions introduced, for example, in WordPress 5.0.0.
Yes, it is possible to read WordPress’s documentation and refer to the “Since” section to be sure not to use this when working with ClassicPress.
However, that is simply unproductive and confusing.
Also, code changes all the time, and having our own, ClassicPress oriented Code Reference is one of the things that stopped me personally and as a developer from using ClassicPress.
I constantly needed to re-interpret WordPress Documentation to ClassicPress.
Probably I am not alone with this problem. It also looks bad, when you want to propose to a prospect to use ClassicPress, but then have to admit that “there is not even a Documentation”.
No more!
The new ClassicPress Documentation Hub now (how familiar!) includes a Code Reference where we can search, browse and consult ClassicPress Functions, Methods, Classes and Hooks.
This also lays the foundations to document ClassicPress’s own code when we start diverging from WordPress.
Who knows, perhaps we will have some better handling of “wpautop” in add_shortcode() in future.
This would then be documented in said Code Reference.
For the nerdy/curious, here’s a bunch of numbers:
We parsed approximately 2814 Methods, 2874 Functions, 280 classes and 2063 hooks from the ClassicPress Code to actual Code Reference Posts.
1130 Taxonomies Terms where used to categorise the Code, and 21057 Post Connections refer each post to the respective “used by” and “used in” sections.
ClassicPress Guides and Guidelines.
Right, there’s more than just code.
We also added new sections for ClassicPress User Guides, Developer Guides and Plugin Guidelines.
These sections will permit us to publish and maintain ClassicPress Documentation in an organized, central and easily accessible manner in future, ready for the avid Users and Developers to be consulted and used.
A Word on ClassicPress Documentation Comments and Editing Documentation
The WordPress Code Reference has a comments section for users to add notes.
We removed that on the ClassicPress Code Reference Posts, on purpose because those comments are often wrong, misleading and even proposing insecure code usage.
They will not be re-added.
If the Code Reference is unclear or wrong, 2 things should/could happen:
- the actual “Code Comment Block” in the source code should be updated.
You can either report such things in the Support Forum, or directly open a PR in the Github Repo. - An explanation, vetted by a developer, and revised for security, should be added to the Code Reference.
If any other, Human Written Documentation such as User or Developer Guide is wrong or unclear, it is suggested to open a Support Forum Ticket and elaborate on the problem.
Feel free to also provide a draft of the “better version”, this is often useful and helps speed up adjustments.
Feedback
Of course, as it is with all things new, this is a Work In Progress (especially regarding the documentation parts written by humans).
It will be extended as we go and have requirements.
We as a community highly appreciate and value anyone’s input, feedback and, of course, help.
If you wonder how you can help: we generate the Code Reference part with a Parser, as discussed above already.
This basically means “the machine” writes everything for us (finally, we use them instead of them using us).
The best way to contribute is to speak up (in our forums) when you see issues, propose new documentation when you recognize the needs for, and volunteer to write eventual documentation if missing (or rewrite existing, if unclear).
The very best way to contribute includes, but is not limited to spreading the word and use ClassicPress!
If you have any feedback on our new ClassicPress Documentation Hub please let us know in the Documentation Forum Category on the ClassicPress Forums.
Concluding
It has been a major pleasure to contribute and see this Documentation Hub coming to life. On a note of “Props and Credits”, it has to be mentioned that we based the Documentation Hub (especially the parsing code to documents part, but also the look and feel of the site) on the existing WordPress Documentation. Without their tools – which are Open Source and available to anyone via SVN – this would have taken weeks, if not months.
Additionally, let’s not forget that a Community consists of their members, thus, special props should be mentioned for helping and sharing input:
@azurecurve For taking on Plugin Guidelines, and helping to test the new system
@james for being the reasoning mind avoiding the young and excited newbies doing things the wrong way, and for helping with server related tasks
@wadestriebel for helping with server related tasks, valuable input and energy
@viktor for taking on writing tasks, and opening several important tasks in the forum related to the new Hub
@kevinhaig who initiated this entire idea months ago already and spent weeks on a fully customised system we did not end up using, but was invaluable in the process
@joyously for valuable feedback and pointing out issues, sharing experience and knowledge from how WordPress does it
@timkaye for valuable inputs also but not limited to legal advice
And of course the entire community who is the core of this operation, and without which, ClassicPress would be just another Fork on GitHub.
That’s all for now!
Stay tuned for exciting news about and from ClassicPress coming soon.
About smileBeda
ClassicPress Nerd, World Citizen and definitely Human.
Thank you @anon66243189 for all your work on this