[Grok-dev] Re: Permissions-tutorial in SVN
uli at gnufix.de
Thu Aug 23 08:07:59 EDT 2007
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).
More information about the Grok-dev