search

GatherPress / gatherpress

Powering our community's event management needs.
https://wordpress.org/plugins/gatherpress/
GNU General Public License v2.0
93 stars 30 forks source link

Update documentation #656

Open carstingaxion opened 5 months ago

carstingaxion commented 5 months ago

Is your enhancement related to a problem? Please describe.

I’d like to enhance the existing documentation. The current README.md houses one part of dev docs, that is going to be moved into the /docs/developer folder with #653 ✅

It might help contributors and extenders as well to have some additional docs about:

docs/developer/

Understanding GatherPress

Extending GatherPress

docs/contributor/

docs/user/

Designs

For now, I recommend, creating static markdown files until a new Playground-powered documentation workflow #765 is ready. A structure with named folders and just one README.md file per directory seems to be the most common way to do that.

The written docs should be accompanied by an auto-generated code reference.

Staying with GatherPress‘ close-to-core philosophy, I’d like to re-use existing stuff and get the benefit of a well-known UI on top. A working PoC for a GatherPress code reference using the same theme as developer.wordpress.org, can be found here https://github.com/carstingaxion/gatherpress-devhub/issues/1#issuecomment-2294166369

Describe alternatives you've considered

No response

Code of Conduct

carstingaxion commented 1 month ago

He @shawfactor, what have you been searching for recently (in the context of GatherPress)? What needs to be in the dev-docs from your extenders-point-of-view? I would really appreciate your feedback over here!

carstingaxion commented 1 month ago

May I invite you too @oscarhugopaz, as you seem to do more development work, than a typical user, would you please add your thoughts here?!

What needs to be part of GatherPress developer documentation?

shawfactor commented 1 month ago

I’ve never looked at the documentation but I managed to understand the code. My only only bugbear was that many methods are protected which are useful for building templates and other plugin extensions. I’ve raised an issue for this already though as there are no security reasons why these methods are not accessible to everyone

carstingaxion commented 1 month ago

I’ve never looked at the documentation but I managed to understand the code.

Thanks @shawfactor, in the name of all who wrote that understandable code!

I felt & feel the same, that’s why I really enjoy contributing to that project! The existing code base is understandable and makes a lot of sense.

Maybe we could keep your statement for a later, as a first testimonial. Accompanying your great review on w.org ;)

My only only bugbear was that many methods are protected which are useful for building templates and other plugin extensions. I’ve raised an issue for this already though as there are no security reasons why these methods are not accessible to everyone

We talked about your issue #635 in last weeks huddle and concluded that the current implementation is based more on a general design decision, rather than being planned for extension. But we agree and are willing to change some of the methods.

Be absolutely invited to open PRs for all changes you see a need for!

shawfactor commented 1 month ago

Completely agree with you.

I swapped my sites over from another events calendar as gatgerpress does things in a true open source way, seems open to suggestions, and plans to work with existing Wordpress plugins

Happy for you to use my words as a testimonial

I believe having accessible methods or some alternatives like template functions is essential though. Buddypress, bbpress, woocommerce etc don’t try to do everything. Instead they benefit from an ecosystem that has grown with them. In order to achieve this, accessing event characteristics like times and descriptions in a flexible way (without having to reinvent the wheel) is essential.

Pere

On Wed, 21 Aug 2024 at 10:32 PM, Carsten Bach @.***> wrote:

I’ve never looked at the documentation but I managed to understand the code.

Thanks @shawfactor https://github.com/shawfactor, in the name of all who wrote that understandable code!

I felt & feel the same, that’s why I really enjoy contributing to that project! The existing code base is understandable and makes a lot of sense. Maybe we could keep your statement for a later, as a first testimonial. Accompanying your great review on w.org ;)

My only only bugbear was that many methods are protected which are useful for building templates and other plugin extensions. I’ve raised an issue for this already though as there are no security reasons why these methods are not accessible to everyone

We talked about your issue #635 https://github.com/GatherPress/gatherpress/issues/635 in last weeks huddle and concluded that the current implementation is based more on a general design decision, rather than being planned for extension. But we agree and are willing to change some of the methods.

Be absolutely invited to open PRs for all changes you see a need for!

— Reply to this email directly, view it on GitHub https://github.com/GatherPress/gatherpress/issues/656#issuecomment-2301940449, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAE55YPC2M7GILHUC7AA3STZSSCE7AVCNFSM6AAAAABHHFNRYCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMBRHE2DANBUHE . You are receiving this because you were mentioned.Message ID: @.***>

carstingaxion commented 1 month ago

The index of docs/contributor could become also the Contribution Guidelines GitHub wants us to add.

image