[Product-Developers] One question, answer once policy to build up the developer manual

[Mikko Ohtamaa]

Hi,

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.

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!

Cheers,
Mikko

--
http://www.twinapex.com
Professional Python hackers for hire







-- 
View this message in context: http://n2.nabble.com/One-question%2C-answer-once-policy-to-build-up-the-developer-manual-tp3294349p3294349.html
Sent from the Product Developers mailing list archive at Nabble.com.