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: Shiro Spring Cleaning!
Date Mon, 22 Apr 2013 01:46:28 GMT
On Sun, Apr 21, 2013 at 2:31 PM, Les Hazlewood <lhazlewood@apache.org>wrote:

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

Maven doxia rendering has been there forever (
http://maven.apache.org/doxia/modules/index.html). APT is just one possible
markup language just like Markdown is (
http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-markdown/).


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

Clunky as in new users just don't pull the code down as the first step. It
was very clear from Tapestry experiment that new users just feel much more
comfortable editing a wiki. I really like APT, Markdown etc. markup
languages but it's still different than WYSIWYG like Confluence.

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

Yeah, moving to git has been a pleasure and a real time-saver for Tapestry.
That's a separate discussion though.


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

SVN to git bridge isn't quite the same. It's far more clunky than plain git.


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

This is how sensitive this is: our user contributions on Tapestry went way
up after we provided an edit link directly on the exported sites, rather
than having to find the right page on cwiki.a.o.


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

Yeah, that's a tough one. There are benefits in both approaches. Tapestry
is still on single documentation although Howard repeatedly complains about
it for much the same reasons. We tried version-specific documentation at
Tynamo (http://tynamo.org) but the reality is that we only updated the
latest version, and the documentation for older versions quickly become
outdated. For user guide etc. the reality is that they are almost never
quite ready when code is ready to be released. Merging changes to multiple
supported version can fairly quickly become painful as the latest version
of documentation diverts enough.


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

Of course you just create version folders in Confluence but it doesn't have
any strong merging capabilities which is a disadvantage.

Kalle

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