where is database description for ez publish??

Wednesday 20 May 2009 3:43:39 am

Agreed! I was just wishing for this <i>again</i> last week.

Cheers,
Heath

Brookins Consulting | http://brookinsconsulting.com/
Certified | http://auth.ez.no/certification/verify/380350
Solutions | http://projects.ez.no/users/community/brookins_consulting
eZpedia community documentation project | http://ezpedia.org

Wednesday 20 May 2009 7:11:47 am

<i>quoting André R.</i>
Share what? Do you really think we have or own secret documentation that we don't want to share with you?
<i>End of quoting André R.</i>

I've been developing on Ez Publish for a while now (since april), and find that the documentation is seriously lacking in many aspects. Now I have not looked at the datamodel really as I have not needed to delve into that yet. I've been working with the ContentObjects, Treenodes etc. And the code documentation is lacking proper explanation of the parameters needed for a function and especially their type and the explanation of that type. Plus the return values are never given, it sometimes gives an idea by saying what the result will be, but there's no explanation again of the type to expect from a function call. Neither does it give the return value in case of errors or results other then what the function normally would return.
I actually have to dig into the code (!!) to find what I normally would want to read in the documentation of a function. And this is costing me a lot of time.

This lack of proper documentation makes Ez Publish extremely frustrating to develop on at times. So to be honest, I can hardly imagine developers working on further developing this piece of software without proper documentation. Which, sorry to say, leads to the assumption that it must be there somewhere with Ez Publish, but might be kept back to gain partners? And to emphasize, this is the feeling I get after working on Ez Publish for a while, I'm in no way trying to accuse Ez Publish of anything. ;)

It also leads me to the question of what the benefits of becoming a partner of Ez Publish are, does this mean that you receive better documentation to help development on the platform? And this is an honest question I have at this time.

Monday 25 May 2009 2:09:22 am

<i>
Perhaps you have something that is not perfect, still its better that nothing and could be shared. Otherwise it will be years until it happens. Or forever.

Does someone know good opensource program to document mysql database? Keys, relations, comments on fields and tables, good visual output. There should be some around, please suggest, so there is no excuse to hold anything back :)
</i>

You can create your own DB visualisation with MySQL Workbench http://dev.mysql.com/downloads/workbench/5.1.html

Creating tables overview is not a problem, relations are a problem. And those has to be added manually same as was done with the old DB diagram. Basically it has to be extended for support of new tables.

eZ Publish uses PersistentObject as most of the relations is defined as foreign_attribute and foreign_class so looking on those information, it should be easy to figure out the relations between tables. Keep in mind also that cascading operations in eZ Publish almost does not exist. As simple thing, what would you do if a user is deleted from the system? We do not delete all content where foreign creator_id key exists for removed user. eZ Publish is very complex in regard to the DB relations, unfortunately only manual maintenance is possible at the moment.

Personal website -> http://serwatka.net
Blog (about eZ Publish) -> http://serwatka.net/blog

Monday 25 May 2009 8:17:13 am

Let's make it clear :

- there is no hidden document at all, wether you are a gold/silver/gold/platinium/diamond/uranium partner or not
- the public documentation is the one we use every day

Learning eZ Publish is hard and the documentation sometimes (often ?) may not help you (I am not saying it is a good thing), that is a fact. If ever you have any question or if there is anything not clear to you feel free to ask a question in the forums.

Sorry for being harsh here but at least it is clear.

Best Regards.

Monday 25 May 2009 9:53:50 am

<i>Quoting zurgutt</i>
You have been working with it for a month? Someone once said to me it takes half a year to grok it and he was right. Of course there was less documentation then and IRC channel was inactive. Have you been to IRC? You should. I think part of the problems you are having comes from misunderstandings. Learning curve is steep.
<i>End Quote</i>

Actually two months now.. Probably a short while indeed, but its long enough to see the consistent lack of proper documentation in the API and code itself.
I've not had a whole lot of questions to ask really, but found answers for those I had on the forums.
The problem is not directly finding answers to questions, but as I mentioned about, the problems that come from having inadequate API documentation, resulting in me having to spend a whole lot of time just to figure out what I need to supply to functions and what the exact result will be when I do call them with those parameters.
I do not see IRC being useful for getting that kind of information. Asking in there for every function call I will have to make on the objects in Ez Publish.

Every self respecting programmer adds at the very least basic information like:
@param ..... explain
@return ..... explain

Tuesday 26 May 2009 2:29:46 am

Kracker,

Oh really?

really.

Their is no way in this life or the next that a company like eZ Systems could function without owning additional documentation (large or small) on their own products. Period. Your just not telling the full truth if you defend yourself on this one ...

Yes and I come from Mars as well...
Code is public, documentation is public we use the same tools as the community does, period. We apply the rules as everyone does: RTFM (Read That Fucking Manual) and RTFC (Read That Fucking Code). If you are not able to understand that, then there is nothing I can for your. You can say I am a liar then I challenge you to prove I did not say the truth.

Tuesday 26 May 2009 3:06:37 am

The truth is the knowledge is shared among the devs that work on eZ Publish and its extensions, we use jabber / irc / skype to ask each other questions all the time, since some guys are more knowledgeable on some parts of the code then others. In other words, it's not written down, it exists in our head. We are very aware of this being an issue, as we feel the pain every time some dev leaves the company, that for instance was the guy that knew most about the template parser/compiler for instance...

We do try to document all new code (ref autload.php and ezcontetclassattribute.php::classAttributeIdentifiersHash for instance) and re factored code (ezsession.php).
But as of now we'll try to document at least minimal description / @param / @return doc on all methods we need to read the code of to understand as well.

Some of us also try to compensate for missing doc by being active in the forum, and give in depth answer whenever we have the time. And yes, we should have a faq where we place the answers, at least the ones that are in depth and highly descriptive, but that is slightly off topic.

So please stop this pointless word fight, its unproductive and as far as I know ezp is open source so we should maybe instead discuss how the community incl partners can contribute more directly in a re-viewable way as you need to read the code quite often as well it seems.

Good thing eZ Coding standard is quite strict though.. :)

eZ Online Editor 5: http://projects.ez.no/ezoe || eZJSCore (Ajax): http://projects.ez.no/ezjscore || eZ Publish EE http://ez.no/eZPublish/eZ-Publish-Enterprise-Subscription
@: http://twitter.com/andrerom

Tuesday 26 May 2009 9:35:17 pm

I suggest the key message here is that we need better ways to work together.

I’ve helped design regional and national programs to help people find new and better ways to do this. A whole-systems approach is needed. I won’t go into details here.

The problems expressed here and in Kristof Cooman’s recent blog entry are all symptoms of this need.

Finding a better way forward is in everyone’s best interests – and doing nothing is likely to lead to progressively more and more problems.

The success and future of both eZ Systems and the eZ community are clearly interwoven. This is why it is useful to think in terms of an overall eZ ecosystem and to solve problems / create value at that level.

At the moment I don’t think eZ has quite come to terms with what this means or what to do about it. Neither, perhaps understandably, has the eZ community. In any case, it is how these groups work together that is important.

eZ Crew, please contact me if you would like to discuss this more. There are clear and practical ways to help the entire eZ ecosystem.

Wednesday 27 May 2009 1:24:10 am

Paul Wilson: That sounds like a commercial message... :)

Wei Dai: You are talking about project V, its off topic but more importantly we would need to find solutions for how we can better work together before that.

eZ Online Editor 5: http://projects.ez.no/ezoe || eZJSCore (Ajax): http://projects.ez.no/ezjscore || eZ Publish EE http://ez.no/eZPublish/eZ-Publish-Enterprise-Subscription
@: http://twitter.com/andrerom

Wednesday 27 May 2009 2:06:48 am

@kracker: <i>(Did I tell you they -only- hand out binary documentation during training!)</i>

For all trainings I have delivered personally or seen delivered from eZ Systems-WE, the deliverables included a complete copy of the slides and and the training exercices in pdf format. I do not know what other format you would expect, but please share any ideas.

What's more, most of the material that makes up the slides is quite similar to the online manual that is available for free to anybody - the added value of the "basics" training being the presence of the instructor, the exercises, and the completeness of the program.

@arnoud: <i>Every self respecting programmer adds at the very least basic information like...</i>

The problem is this "very least" stuff is quite new in terms of computing practices, and a lot of eZP code is old, ie. it was written before javadocs and unit tests where commonplace. Documenting new code is easy, documenting old one is much harder. But sometimes people do: http://pubsvn.ez.no/websvn2/revision.php?repname=nextgen&path=%2Ftrunk%2F&rev=23604

@Łukasz <i>Creating tables overview is not a problem, relations are a problem</i>

I have had this crazy idea lingering in the back of my head for a while: what about finding out those foreign keys and test implementing them in the db, using not on-delete-cascade? Since eZ code takes care currently od deleteing relations in the proper order, almost everything should work, and the parts that do not are spots where we should improve the code. Anybody has ever tried that?

@Wei: a big-switch over to ezc code was considered and rejected, as it would take too long to recode everything and it would be too risky and too harsh on existing extensions / sites. The switch will happen, but gradually.

Principal Consultant International Business
Member of the Community Project Board