Hi guys,

I’m glad to see the new documentation. It was much needed and the new design is refreshing and clear.

However, something I miss from the docs is more information about the internal working of the things. For example, in the tutorial “Working With Field Relationships”, basically you say to use:

‘relate’ => array( ‘scope’ => ‘post’ )

to make relations, and then you explain how to query them.

That certaninly helps, but is just the tip of the iceberg. If I’m new to piklist I want to know what kind of relationships are supported. Then I want to know where the data is stored (I can’t understand that there is no mention of “__relate_post”!). I want to know what $field[‘relate_to’] and $field[‘relate’] have to do about the relationships, and what other things can I put in the ‘relate’ array, like ‘field’ and ‘query’. That’s what I miss.

In other places, like the Field Parameters page, I know it is not very fun to document things, but most of the people will approach piklist by checking what can a field do, and it is a shame to see that there are quite a few parameters that doesn’t have any information about what they do. You don’t need to write a lot about them, but at least one or two lines with their purpose will help a lot to the people not familiar with them.

Last but not least, I also miss some “high level walk” about how piklist works. Just a high level explanation of what happens when a page load and what happens when you save a page. For example, for class-piklist.php, with a little bit of info about the core helper function, and how process_parts, process_parts_callback, validate_part and render interact, and some information about class-piklist-form.php and class-piklist-validate.php you have help a newcomer immensly and he will be confortable following the source code in almost no time. That should not take more than one day for a person that knows the nitty gritty about piklist, like steve or kevin.

Sorry for the long post and thank you for your work!
Manu