shiro-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tauren Mills <tau...@groovee.com>
Subject Re: Versioned Reference Manual
Date Thu, 19 May 2011 17:49:23 GMT
Les,

A while back I was thinking about ways to elegantly display versioned
information and had some UI ideas. My solution was to keep everything on the
same page, but use client-side Javascript to dynamically show and hide
different versions. This wouldn't be at all hard to do, but I haven't
actually implemented it yet. I'll share the basic concept here -- perhaps
you might find it worthwhile.

Take http://shiro.apache.org/web.html as an example and imagine docs are
marked up like this:

<section>
  <h1>Apache Shiro Web Configuration</h1>
  <p>...</p>
  <h2>Default Configuration</h2>
  <p class="ge1_2">In Shiro 1.2 and later, standard web applications...</p>
  <p class="le1_1">The simplest way to enable Shiro...</p>
  <div class="ge1_2">
    <h3>Custom WebEnvironment</h3>
    <p>By default the EnvironmentLoaderListener...</p>
  </div>
  <div class="eq1_1 eq1_0">
    <h3>Custom Path</h3>
    <p>If you do not want to place..</p>
  </div>
</section>

At the top of a page (and maybe even next to each block) would be a
javascript widget that allows users to select the documentation version they
would like to view. Each version number would appear in a toggle button, so
that multiple version could be viewed at the same time. The [Latest] button
would be selected by default:

[Latest] [1.3] [1.2] [1.1] [1.0] [All]

Javascript code would determine which classes should be hidden and which
should be shown. The class names would represent a specific version (eq), a
version and older (le), or a version and newer (ge). So if [1.3] is
selected, classes eq1_3, ge1_2, ge1_1 would be shown and eq1_1, le1_2 would
be hidden.

In addition, CSS would be used based on the class names to add a version
number in the page margin next to each paragraph, section, callout, title,
or whatever. I'm imagining this as a list of small version numbers in a
light grey text to either the left or right of each "block" on the page.

Content without a versioning class would be shown at all times.

This would allow you to write the documentation all on a single page, but
only show what matters for a particular version. It also makes sure to
reenforce the version number that a specific block of content pertains to
all through the page. If multiple versions are being viewed at the same
time, the older versions could be slightly dulled with the text in a lighter
 grey so that it is obvious what is new and what is old.

Just some ideas. I'd be happy to write the javascript widget if you decide
to go this route.

Tauren


On Thu, May 19, 2011 at 7:30 AM, Les Hazlewood <lhazlewood@apache.org>wrote:

> On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
> <kalle.o.korhonen@gmail.com> wrote:
> > 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.
>
> This also doesn't work out well in my experience - there is no way to
> easily do this if you're adding a new feature or using an alternative
> to an existing one.  The example here is the web documentation I just
> added - in 1.2, it is done one way, in 1.1 a different way.
>
> I may be being dense here, but I can't see how to represent that
> information easily in the same page without introducing inelegant
> documentation chunks based on version.  I'd love to hear suggestions
> on how to improve this for example.
>
> Best,
>
> Les
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message