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

Dylan Jay djay at pretaweb.com
Fri Feb 10 13:44:15 UTC 2012


On 10/02/2012, at 8:58 PM, Mikko Ohtamaa wrote:

> 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.

disagree with this point. We tried one way to get the sphinx docs  
indexed and we didn't have access to plone.org so gave limited options.
I think having the docs on plone.org (and rtd) is very important. To  
be honest having an external content integration story for plone is  
long overdue.

>
> 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.
> _______________________________________________
> Product-Developers mailing list
> Product-Developers at lists.plone.org
> https://lists.plone.org/mailman/listinfo/plone-product-developers



More information about the Product-Developers mailing list