Technical Docs need some valuable improvements

[Marketing]

I have a couple issues with how the documentation is being handled. I’m doing a few customizations here and there, for example to month and list view. Sometimes I have to look up functions in the technical docs. Here are the problems I see the most, which limit my (and presumably other developers’) productivity:

For my comments below, use the following page as a guide to understand my issues:
Function: tribe_events_get_days_of_week

(1) Acceptable function parameters are rarely (if ever?) explained.

The page for tribe_events_get_days_of_week does not explain what $format can be. I initially assumed it matched the PHP date formatting string, and tried passing “D” as the parameter to get the 3-character abbreviations for the days of the week. That did nothing though, so I dug into the function source and saw that, oh there’s two valid parameter values: “min” and “short”. It sure would be helpful to see those parameter values listed on the technical docs page for the function, and with a description of what gets returned by the function when those parameters are used.

This issue is applicable to many technical documentation pages. It would be great to have parameter values explained much better. Isn’t technical documentation supposed to serve that purpose—fully explain all aspects of the topic that the page is about?

(2) The examples section doesn’t contain actual examples of how the function is called.

Another puzzling issue. It would be helpful indeed to see real examples of the function being used. That would frequently nullify the above issue; samples of actual function calls can provide insight into valid parameter values and what the returned data will look like. It makes little sense to give developers the “prototype” to the function and call it an example. That kind of information would normally appear near the top of the page, above the parameters summary.

These two issues would not be trivial to fix across all the technical documentation pages, I understand that. However, I think that someone updating a few functions per day isn’t unreasonable. In time, all the pages would be up-to-date and the information contained would be that much more helpful to us developers. Of course I can look things up in the PHP source, but isn’t the point of providing online technical docs to save developers from having to dig through all of that code?

Thanks for listening, Modern Tribe.

[Trisha]

Hello!

Thank you so much for taking the time to write to us about this! I agree with you that our Knowledgebase needs some improvement, feedback like yours goes a long way in helping us understand how it’s used and how it can be improved.

We have plans to begin reworking the documentation soon. It was a topic of discussion at our annual team retreat just a few weeks ago. As you said, it will take time but it is something we are committed to making happen.

Stay tuned!

Cheers,
Trisha

[Support Droid]

Hey there! This thread has been pretty quiet for the last three weeks, so we’re going to go ahead and close it to avoid confusion with other topics. If you’re still looking for help with this, please do open a new thread, reference this one and we’d be more than happy to continue the conversation over there.

Thanks so much!
The Events Calendar Support Team

[Author]

Posts