[Product-Developers] Thinking about a roadmap for docs + products infrastructure

Mikko Ohtamaa mikko+plone at redinnovation.com
Fri Feb 10 09:58:33 UTC 2012


Hi,

Just few points

* Don't even think about versioning documentation, before core developers
would update documentation regarding new releases. Until then it would be
wasted effort. I don't see this happening near future, or during our
lifetimes

* Also making docs indexable by plone.org has been problematic in the past,
because plone.org is a such bitch as it is, and added values vs. the cost
for this task might need to be considered. Just redirect developers properly
to the right documentation and take down all bad documentation on plone.org
. This is also a point for SEO.

The developer manual polishing does not really matter until very visible
issue in the very first steps of the  

1) buildout does not work out of the box, even after 3 years: 

http://plone.293351.n2.nabble.com/Buildout-and-fearsome-system-wide-Distribute-upgrade-loop-solution-available-tp7234343p7237039.html

2) zopeskel 3.0a1 made all paster tutorials useless (incl. books). There was
discussion to take down this release, but the authors didn't agree. ZopeSkel
work seems to come halt so you need to stick with working 2.x releases until
all the code is ported. 

What one needs is to regarding documentation / developer friendliness

1) Fix buildout so that you can simply run it on any system, including
Windows. Please note that "90% of Plone downloads" are for Windows. We know
what's wrong, but someone needs to jump on people until it gets fixed.

2) Create a GitHub repo for working buildout.cfg which has ZopeSkel and
Paster installed, ready for clonable. This buildout.cfg should have version
pindowns (no ZopeSkel 3) and "batteries" included for development work, like
i18n tools. Possible starting point: https://github.com/Jarn/buildout

3) Write a working Dexterity tutorial against the new recommended
buildout.cfg this
http://collective-docs.readthedocs.org/en/latest/tutorials/addon.html


 

-----

Follow me in Twitter 



Read my blog 





--
View this message in context: http://plone.293351.n2.nabble.com/Thinking-about-a-roadmap-for-docs-products-infrastructure-tp7268108p7272153.html
Sent from the Product Developers mailing list archive at Nabble.com.


More information about the Product-Developers mailing list