Better docs would be great thing!

[Figoli Quinn]

Hey folks,

As they say, two roses and a thorn!

No. 1 (rose): this is a really good plugin
No. 2 (rose): I’m impressed with responsiveness of your staff here on the forums.
No. 3 (thorn): As a paying customer of Events Calendar Pro, I’d love to see better documentation for developers working to customize the program. Many of the docs, including function and hook descriptions, seem incomplete, inadequate or nonexistent.

Having just been through a wrestling match with tribe_get_events() — ending up I’d say in a draw ( https://theeventscalendar.com/support/forums/topic/ordering-events-by-title-query-not-working/#post-1009161 ) — I would suggest that function would be a great place to start. A little more completeness on how to deal with custom queries would be helpful. For example, something like “TribeHideRecurrence” does not seem to be mentioned anywhere that I could find in the docs, but it does something important. And also better descriptions of hooks.

My idea of good docs, would be along the lines of this: http://www.advancedcustomfields.com/resources/

Look at some of the function documentation — usually very helpful, extensive and complete. A lot like the regular WP Codex.

I know it’s probably super time-consuming, but maybe better docs would result in fewer forum posts, and saving you all some time in the end.

On the other hand, maybe Events Calendar isn’t really meant as a development tool, but as more of an end product. In which case, customization isn’t something you are concerned about.

Anyway, just some feedback from a mostly happy user. Thanks very much.

Bob

[George]

Hey Robert,

First of all, thank you for the kind words about the plugin. I’m glad that it’s not all thorns! 🙂

But I genuinely feel your pain with some of our documentation. We work hard on it, and I’m not downplaying what our efforts have been thus far, but our documentation is actually something that we’ve been discussing a lot recently. We know we can be doing better, too, and feedback like yours here only adds to the awareness that things can be improved.

I also agree with you about Advanced Custom Fields having great documentation – they truly nailed their documentation and it’s a level of thoroughness we are striving for.

Your comment here is interesting, too:

On the other hand, maybe Events Calendar isn’t really meant as a development tool, but as more of an end product. In which case, customization isn’t something you are concerned about.

We definitely do care about having The Events Calendar be a developer-friendly plugin, and one of the things we’re most proud of about The Events Calendar is how easy (relatively, and with a big asterisk depending on the project of course!) it is to customize. We’ve used it in some great and creative ways for many client projects of our own.

But that doesn’t mean we’re doing as good a job as we can at making it easier for other developers to have such flexibility, too.

I’m sorry that you had to wrestle so much to get tribe_get_events() working as you wanted – I’m glad you got things working, but agree with you that the documentation should’ve been able to help you get it working in much less time.

Thanks for your feedback Bob. What do you think about what I wrote here? Do you have any more specific items about the documentation that you can see being improved?

Thank you,
George

[Figoli Quinn]

Yes, appreciate your comment here. I wouldn’t underestimate the time and effort that are required for thorough documentation of a plugin of this complexity (not just initially, but also in keeping it up to date).

I’m happy to hear you’re looking at this.

Another thought on the docs would be better organization of functions and hooks — not just alphabetically, but topically. And not mixing deprecated functions (there are a lot of those!) with those you want people to use.

Good luck, and thanks for a great plugin.

[George]

Thanks for the additional feedback Robert, this bit especially:

Another thought on the docs would be better organization of functions and hooks — not just alphabetically, but topically. And not mixing deprecated functions (there are a lot of those!) with those you want people to use.

I’ve noted your ideas and our documentation is an ongoing project, constantly changing and (hopefully!) improving. Our function/hook reference is actually one of the things we talk about changing most often, so stay tuned to the site! We try to push site updates every month or two 🙂

Best of luck with your project(s) in the meantime, Robert, and thank you again for the candid and constructive feedback here.

Cheers!
George

[Author]

Posts