[Grok-dev] Versions field in Grok Documentation

[Peter Bengtsson]

2008/5/20 Kevin Teague <kevin at bud.ca>:
>
> On May 15, 2008, at 6:13 PM, David Bain wrote:
>
> Is there anything different about permissions in grok 0.12?
>
> I ask because the permissions tutorial claims to be specific to grok 0.11.
>
> http://grok.zope.org/documentation/tutorial/permissions
>
> If everything is the same then the tutorial should be flagged as 0.12
> compatible.
> .
>
> I just fixed this by making the Versions field for this tutorial blank.
> The Versions field is a bit tricky for the Grok Documentation, because PHC
> puts up a large, "This content is outdated" message if you mark content as
> specific to 0.11 and 0.12 is released. If we pin all content to specific
> versions of Grok, there will be a lot of misleading "outdated" messages
> since it would be a lot of work to review all content as releases happen
> several times a year. Ideally the Versions field could be parsed the same
> way egg versions are so you could specify a range (e.g. ">= 0.11,<2"), but
> for now ...

I think the version field is a great benefit to the documentation.
Lots of fast moving projects suffer from outdated documentation, like
zope.org

> For documentation covering stable aspects of Grok we should leave the
> Versions field blank. When new releases are made, we look at an
> incompatibilities introduced and search for now outdated documentation and
> mark it as such. This way documentation is "current until proven outdated"
> instead of "outdated until proven current".

That's it. If it's not relevant, leave the version input alone but I
disagree that you should remove the option to specify the version.

>
> _______________________________________________
> Grok-dev mailing list
> Grok-dev at zope.org
> http://mail.zope.org/mailman/listinfo/grok-dev
>
>



-- 
Peter Bengtsson,
work www.fry-it.com
home www.peterbe.com
hobby www.issuetrackerproduct.com