Mailing-List: contact dev-help@shiro.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@shiro.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CA+=EWnAbaq-CrGSmkT_qJpRe1PmyQADEymwMczFGN6mzrH-1xw@mail.gmail.com>
References: 
 <CAAtvD4XAKLm+GokRF-=fB89X_WmVE9-bTvaQBnmwyfBQmCLE5Q@mail.gmail.com>
	<CA+=EWnAbaq-CrGSmkT_qJpRe1PmyQADEymwMczFGN6mzrH-1xw@mail.gmail.com>
Date: Sun, 21 Apr 2013 14:31:41 -0700
Message-ID: 
 <CAAtvD4Vicw6+k2DjTDAD+2cdiOZT+dsrP7N9Yb3N-7oWC7VdLA@mail.gmail.com>
Subject: Re: Shiro Spring Cleaning!
From: Les Hazlewood <lhazlewood@apache.org>
To: dev@shiro.apache.org
Content-Type: text/plain; charset=ISO-8859-1

> As Ulrich has alrealy mentioned to you, publishing Confluence content via
> svnpubsub works fine and at least CXF, Camel, and Tapestry are using it.

Yep, thanks to Ulrich, I used the camel-based maven project to extract
Shiro's existing Confluence content:

https://svn.apache.org/repos/asf/shiro/site/

This repo location currently uses SCMS to generate a fully rendered
site in around 2 to 5 seconds.

> So this is similar to Maven sites with APT although with a different
> dialect?

I think technically that is correct (I've never heard of APT before,
so I just looked it up).

The huge difference here though is that Markdown is THE dominant
simple-text-based-markup dialect out there.  Nothing else comes close
and it is nearly ubiquitous thanks to GitHub.  For example, there are
at least 35 different authoring/rendering tools for it on the Mac
alone.  I'd be surprised to hear of even one such tool for APT.

> It works for some things but it's too clunky for users in general.

Clunky in what way?  I'm sure this comment is based in experience, but
I'd like to learn/understand how, as I do want things to be easy to
use.

At Stormpath while working with dev consulting shops, we've seen
strong evidence that moving to Markdown (plus maybe git) helps
significantly with community contributions to documentation.  They've
told us they saw these benefits when they moved their docs to GitHub.

For anyone that uses GitHub for example, it's trivial to fork a repo,
make some edits, and then immediately issue a pull request back to the
content team.  This is much lower friction for most developers than
learning the ASF's specific approach to Confluence.

And because Shiro has a GitHub mirror, I think we'll see the same
benefits (pull requests can easily be turned into patches for SVN
until we as a team decide to move to Git).  Also note that we don't
have to be on GitHub - this same paradigm/flow for making
contributions is second nature to most devs.  Contributing to
Confluence isn't as much.

> Wiki is the best way to include and allow the community to contribute. When
> Tapestry made it easier for users to contribute we started getting
> significantly more contributions.

Can you please explain what it means when they 'made it easier for
users to contribute' to Confluence?  I'm curious to know what this
means so we can contrast it with the Markdown/patch or pull request
model.

> I think the path of least resistance is
> keeping Confluence content and change it to export via svnpubsub.

Because I was testing SCMS yesterday, our content is now also in
https://svn.apache.org/repos/asf/shiro/site/ and this statement (least
resistance) is no longer true - either approach is low friction now.
Actually, I would argue the camel site approach is more work since
we'd have to set it up for our project to run regularly as I just
hacked it out to run manually one time.  SCMS is already in place and
works without further modification.  But, that's a minor issue.  I
think the important thing now is that the dev team (and extended
community who cares about authoring) decide which approach we should
go with:

1. We author content in Markdown and render the site via SCMS.
Publish via svnpubsub.
2. We author content in Confluence and render the site via the camel
site code.  Publish via svnpubsub.

One thing I am very concerned with however, and have strong feelings
towards, is choosing whichever allows us to manage documentation for
Shiro release versions well.  By this I mean the following:

It has been a constant pain for me and others writing the Reference
Manual for different versions of Shiro.  The way we do it now is with
bold sections saying *this only applies to Shiro version XXX*.  This
is a hack and introduces unnecessary noise into the docs and often
confuses people.  This should be cleaned up asap.

In other words, when we release Shiro 1.2.2 there should be static,
permanent docs that pertain exactly to version 1.2.2.  When we start
adding content for, say, Shiro 2.0.0, those docs should exist and be
tailored for Shiro 2.0.0.  When we release 2.1.0, those docs should
pertain only to 2.1.0, etc.

Additionally, these docs should live in perpetuity.  This way, as
Shiro end-user, I know if I'm using Shiro 2.0.5 for example, I know I
only need to go to the 2.0.5 docs and I don't have to worry about
extraneous or invalid documentation that doesn't affect me.  So I
would expect to see something like this:

http://shiro.apache.org/docs/1.2.2/
http://shiro.apache.org/docs/2.0.0/
...
http://shiro.apache.org/docs/2.0.5/
etc.

Now, I know I can do this trivially with Markdown and svn or git: upon
releasing the software, I just copy the existing reference manual docs
to a new directory and then modify that one as we're working on the
next version.

Also note that I'm mainly talking about the reference manual versions
here - the entire site wouldn't need to be copied on every release.

If not using Markdown and a vcs, how would we achieve this easily in Confluence?

Cheers,

Les