[Grok-dev] Re: Permissions-tutorial in SVN

[Uli Fouquet]

Hi there,

Am Donnerstag, den 23.08.2007, 10:42 +0200 schrieb Jan-Wijbrand Kolman:

> > I wonder if we should set a policy for this. Personally I would prefer
> > that documentation, especially documentation appearing on the website,
> > documents the last release instead of as-yet-unreleased code.
> 
> Well, then the documentation on the website should not be generated from 
> the trunk, but from the released version I'd say. We could even generate 
> a second set of documentation pages on the website explicitely for the 
> trunk of grok.

>From a maintainers point of view, this sounds good: once released, a
text doesn't have to be touched anymore. 

>From a "users" point of view: wouldn't that be confusing? Imagine
someone installed the subversion version (as offered on cheeseshop). Now
s/he is working with the tutorial, tries to use define_permission and it
breaks everything (or the other way round: using release-version with
grok.Permission). This might be frustrating and a short remark in the
tutorial (as I did in Luis' tutorial) could avoid this effect. 

Beside this: +1

Anyway, we might require 'version-tags' in every tutorial, saying which
version it covers. If this is made bright, fat and blinking enough,
users could be encouraged to check their installed versions before
reading the 'wrong' tutorial. 

> If there's a strong wish (and I can certainly see that use case!) to 
> include the "older" permissions tutorial on the website, I guess we 
> could create an 0.10 *branch* or something, where documentation relevant 
> for that release is evolving?

The "older" permissions tutorial covers the current official release.
>From my point of view we should definitely make it available on the
website (with the FIXMEs removed). But yes, this might happen from a
branch or something.

> Another thought that just popped up: You could argue documentation 
> should follow the same pattern as formal deprecations (but we're not yet 
> doing formal deprecations).
+1

Kind regards,

-- 
Uli