shiro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Les Hazlewood <...@hazlewood.com>
Subject Re: Versioned Reference Manual
Date Thu, 19 May 2011 14:25:14 GMT
On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
<kalle.o.korhonen@gmail.com> wrote:
> 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.

This may work with Tapestry, but it hasn't for Shiro - in the last 8
months, with one exception as a Jira contribution, no one has
contributed to wiki documentation other than Alex and myself.  I'm not
complaining mind you - just stating that this hasn't been working for
our project, so I believe we need an alternative.

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

In practice, you only update the current documentation that is paired
with your current API as you work on that API.  Once a version is
released, that doc is not edited again, since it only applies to the
software released with it.  No one ever reads the Hibernate 3.1
documentation if they're working with Hibernate 3.6

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

While I believe you're right (JavaDoc is inherently versioned, and
could solve our problem), in my experience, this is not something
people want - no one likes reading JavaDoc as the primary
documentation mechanism.  Everyone I know would prefer a nice HTML or
PDF reference manual they can open up and read at their leisure.

It's a matter of behavior IMO - when you read JavaDoc, you do it in
the context of programming.  When you read a reference manual, you
usually do it when away from code, so you can read about features,
behavior, general background, etc, more like a book.  This is a lot
more 'digestible' and user-friendly than being barraged by a bunch of
API methods if you've never used the framework before.

Does anyone feel differently?

Regards,

Les

Mime
View raw message