Plone developer API documentation could be better. For this very reason, people ask questions regarding how to do a simple thing or two in Plone code. Asking questions is often the only way to fight through the monstrous codebase. Luckily these questions usually receive answers from the active community in product-developers@ list and IRC. See also prior mailing list dicussion.
However, asking the same questions again and again, or asking the question in the first place, is undesirable way to proceed. A proper way to fix the problem would be have a proper documentation voiding the need to ask the question in the first place. Since documenting Plone API is a huge task, I propose the following to get things bootstrapped:
1. Wherever and whenever someone asks a question regarding Plone code development do not answer directly
2. Instead, write the example code snippet and commit it to https://svn.plone.org/svn/collective/collective.developermanual/trunk (collective commit access needed)
3. Give the link to the SVN trunk file as an answer This way we should slowly start building up a “developer reference” which covers the most common API use cases.
https://svn.plone.org/svn/collective/collective.developermanual/trunk is a mess. Do not care about this little detail. Just toss in your .txt files. The docteam and I will properly proof-read and structure it in the future. As soon as we code snippets keep flowing in I am happy!
1. Example
Here is how I helped some unlucky person struggling with DataGridFrield and created some documentation during the process.
Private email question:
I have been using your excellent DataGridField add-on on a projet, where as webmanager I add variable lists of information within an objet. However now I would like to build a script that would insert new rows and content automatically : let’s say a User calls a specific objet ‘A’ from time to time, I would like to have a DataGridField that will record incrementally these calls (with columns like “when”, “how long”, “what result”) each time they are made, without the User having to do anything.
I tried to find an answer in the code but I’m not fluent enough in Python yet to understand everything I read. Could you tell me how I could build that script or where shall I look for clues ?
Private email answer:
Please also read some guidelines I tried to come up for documentation.
I came to the same concept for streamlining customer support, where each visit to a question is an opportunity to improve the response rather than write another one.
Organization and discipline are already a problem, but I absolutely agree in concept. There’s a good way to do this, though I’m not yet sure what it is.
I have to say that your common recipes is always one of the first places I look for a quick answer. About the time I first found it I had been starting my own which I quickly abandoned in favor of yours.
Pingback: Plone Developer Manual, take #0.1 | Twinapex Blog