Posted: August 17, 2018 at 7:06 pm
|
|
Until about half a year or so ago, there used to be a good documentation for developers, with e.g. a searchable object browser and some decent examples. This has all gone. Where did it go? Today there is of course http://developer.eventespresso.com/, but frankly, it sucks big time, even for a blog (no categories, no search…). And then there is the Github repo, which is not much more than an annotated code repo. Try finding an action hook or a specific function – good luck with that. I’m glad I finished most coding when the documentation was still online, so I know my way around a little. If I had to start today, I’d probably choose another framework, due to lack of documentation. |
|
Hi, I’m not aware of any documentation being taken down. The developer documentation resides here. If you have any further feedback about the dev team’s documentation efforts, feel free to open an issue on GitHub. The developers welcome any ideas for improvement. |
|
|
|
I remember where it was: code.eventespresso.com |
|
You can access the same information that was there, with the added bonus of the information being up-to-date, by opening up the Event Espresso plugin in an IDE. One of the troubles with the code.eventespresso.com site was the information was out of date and was time consuming to keep up-to-date with newer versions of Event Espresso. For example, the old auto-generate code site had this for the EE_Gateway class: http://code.eventespresso.com/class-EE_Gateway.html which had a list of methods & properties. The same information is in the class file found here, or open the EE_Gateway.lib.php file in your IDE: You’ll note the current version has new methods that weren’t listed in the code.eventespresso.com site as its information was out of date. |
|
|
|
I’m puzzled; how can an auto-generated site be out of date? |
|
Thank you for leaving this interesting feedback. I’ll try to elaborate a bit further because I did mention earlier that documentation is provided but maybe I can do a better job explaining this. First though, since you asked:
It’s autogenerated from whatever the version of the plugin was given to the PHP doc generator at the time. Each time there was a new version, someone would need to manually update the PHPdocgenerator site & rebuild it to include the new version of EE. So it was autogenerated, but not wired up to a code repository or anything like that. So it was usually out of date. Along with that, we found from chatting with developers that they said they preferred searching the code base with their IDE or even on Github over the code.eventespresso.com site. So that was one of the reasons they took that site down. The other was the amount of work/time it took to keep the site up to date (sometimes there are 3 or more updates a month) so the site generator would have to be manually updated each time to stay up to date.
If you use an IDE like PHPstorm or even SublimeText3, you’re probably familiar with their excellent search tools, and how you can click on methods in the code and it will show links to method definitions and class properties.
This comment makes me wonder if you’ve actually looked at the documentation, because the documentation does indeed have a table of contents. You’ll find it here: https://github.com/eventespresso/event-espresso-core/tree/master/docs#table-of-contents Each topic has an introduction. For example, the Messages system documentation has an overview: Another example, of the model class diagram The documentation also has code examples, tips, and a hook reference. A few examples include a variety listed here: and really, most articles in the documentation are packed with code examples and tips. The documentation is far from a complete start-to-end guide but the dev team does make an effort to keep the documentation articles up-to-date and when they add a new component that needs documentation, that gets done. If you have some constructive feedback about the documentation that’s been provided we’d love to hear it. |
|
|
|
Thanks for your elaborated answer. 1. Following the info on https://github.com/eventespresso/event-espresso-core/blob/master/docs/A–Best-Practices/ee-actions-and-filters.md, I conclude I need an action hook. Would you say that is the normal line of working with a third party library? From the fact that people prefer browsing code through their IDE, I would conclude that the current documentation is inadequate, not that it is unnecessary. In my case, I think a decent documentation of the action hook and when it is invoked and its parameters (and I mean more than “Oh, that’s an array”) and the EE_Registration class with some examples would have saved me a lot of time. |
|
|
Hi Sara, Thanks for raising your concerns about developer documentation. I also appreciate a concrete example of where it is currently lacking. As Josh pointed out there were a number of reasons to abandon the auto-generated I’d like to take a moment to address this question > Would you say that is the normal line of working with a third party library? I think “normal” is always a bit relative. Things like size of the library, number of developers working on it, the complexity of the library, whether the developers even care etc. all contribute to the amount (and usability) of documentation that library has. So in my experience its been hit and miss in the libraries/frameworks/plugins I’ve worked with. I do agree with you that when I encounter a library that has useful and complete documentation it’s refreshing and sometimes (not always) saves time over doing a process similar to what you described. What I think is important for me to be clear on, is that our team DOES take seriously developer documentation (some insight into that can be found here: http://developer.eventespresso.com/changes-with-developer-documentation/). So we take pains as developers on the team to try and keep that documentation up to date with new features and systems (for instance, take a look at the documentation we’ve been working on in our Gutenberg branch. Generally speaking though, we do not cover everything (things like hooks etc that you’ve pointed out). The reason for this is quite simple, time. Being a small team, we have to make choices about things we spend our time on and so we’ve decided that we will focus more on documenting overall systems and major bits of code, other code that we perceive might be self-explanatory in the code itself we leave as is for now. We don’t always get those decisions right but this allows us time to work on the bugs/features etc that affect our codebase. So its the age old, “We document, but not as much as we like”. Another important thing is that we pay attention to people who write helpful feedback on where the documentation is lacking and what they had trouble figuring out. If we see a pattern in questions or requests from developers show up as issues in github (or elsewhere) that reveal a deficiency in documentation, we’ll try to address that by improving/writing additional documentation. That’s why Josh was reaching for a concrete example from you in this thread so we could consider that in future documentation updates. Hope that helps! |
|
|
Thanks for the concern and time. Still it saddens me that so much great software is being developed without proper documentation (Google is another example – great tools, crappy documentation). To cut the discussion short, what would help me most (ordered by importance, high to low): 1/ list of all EE_ classes in db_classes, especially with a brief description of each db field (which I now have to inspect with PhpMyAdmin or var_dump’s) and inherited methods/properties (which are harder to find), and if possible its own methods/properties That would be great. |
|
Thanks for the feedback! |
|
The support post ‘Where did the EE4 documentation for developers go?’ is closed to new replies.
Have a question about this support post? Create a new support post in our support forums and include a link to this existing support post so we can help you.
