shiro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kalle Korhonen <kalle.o.korho...@gmail.com>
Subject Re: Versioned Reference Manual
Date Wed, 18 May 2011 22:26:31 GMT
On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <lhazlewood@apache.org> wrote:
> The other great benefit of this is that if anyone wants to contribute
> to documentation, they don't need to have a wiki account - they can
> just provide patches against the project.  That's really nice IMO.
> What do you guys think about moving to a versioned documentation approach?

Well, here's a real world data point from Tapestry project. Tapestry
used to have APT-(Almost Plain Text) based, versioned documentation
but we didn't get *any* documentation patches from users. Since moving
to a wiki-based system, we've gotten lots and lots of users
contributing to the documentation with fixes, new sections and
re-organizing the content. The problem with versioned user guides is
that you'd have to keep updating multiple versions since documentation
often needs improvements throughout the lifetime of a particular
version and in practice, people seem me to be only reading and
improving documentation for the latest version. Javadoc is versioned
already, so I'd say the most practical and most cost-effective
solution is to write the user guides etc. in such a way that they are
as version agnostic as possible and then refer to the Javadocs when
things differ.

Kalle

Mime
View raw message