Versioned Reference Manual

classic Classic list List threaded Threaded
22 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Versioned Reference Manual

Les Hazlewood-2
We've been using the wiki to write documentation so far.

However, I've been having a lot of problems updating documentation to
reflect new/upcoming features, resorting to '<= 1.1' and '>= 1.2'
section headers, and callouts and such to indicate current vs old vs
upcoming features.  Yuck.

Many successful open-source projects have moved to a DocBook file
format that can be versioned in version control along side code
changes (Hibernate, Spring, etc).  Then published documentation for a
release coincides with the features in that release.  And they
typically provide 3 convenient outputs (html, html-single-page, and
PDF).

Sonatype has open-sourced (ASL 2.0 I believe) an example documentation
project that they use to write their book.  We could use that same
project to have a 'refmanual' maven model so that documentation is
always sync'd with Shiro's code.

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?

Les

P.S. if there are concerns about writing DocBook XML, the guys at
XMLMind can be contacted for a free license for their XML WYSIWYG
editor to do Open-Source work: http://www.xmlmind.com/xmleditor/
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Tauren Mills
I like the idea of having versioned docs very much. And I also like
being able to output to html, single-page html, and PDF. However, I'm
not sure DocBook is the way to go.

Perhaps I'm mistaken, as I've never used DocBook before, but anything
XML based makes me cringe! Even if there is a nice WYSIWYG editor, I
can bet that many people wouldn't take the time to find it and use it.
It seems like this would discourage people from helping with
documentation.

What about hosting the documentation at github? Github projects can
have hosted pages that are backed by files in a git repo. And they've
added a REALLY COOL feature now that lets you view a file, click the
"Fork and edit this file" button, and edit it right in your browser.
When you are done, click the "Propose File Changes" button and it will
automatically submit a pull request. Of course, people can still check
out the repo and edit locally if they prefer.

If this could be combined with documentation files that are formatted
in Markdown or some other very easy to use (non-XML) format, it would
be dead simple to do documentation. In my opinion, this would really
lower the barrier to entry, which in my mind is half the reason people
don't contributed to documentation more.

My 2c...

Tauren



On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <[hidden email]> wrote:

> We've been using the wiki to write documentation so far.
>
> However, I've been having a lot of problems updating documentation to
> reflect new/upcoming features, resorting to '<= 1.1' and '>= 1.2'
> section headers, and callouts and such to indicate current vs old vs
> upcoming features.  Yuck.
>
> Many successful open-source projects have moved to a DocBook file
> format that can be versioned in version control along side code
> changes (Hibernate, Spring, etc).  Then published documentation for a
> release coincides with the features in that release.  And they
> typically provide 3 convenient outputs (html, html-single-page, and
> PDF).
>
> Sonatype has open-sourced (ASL 2.0 I believe) an example documentation
> project that they use to write their book.  We could use that same
> project to have a 'refmanual' maven model so that documentation is
> always sync'd with Shiro's code.
>
> 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?
>
> Les
>
> P.S. if there are concerns about writing DocBook XML, the guys at
> XMLMind can be contacted for a free license for their XML WYSIWYG
> editor to do Open-Source work: http://www.xmlmind.com/xmleditor/
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Jared Bunting
I like the idea of versioning the documentation in the same source tree
as the project itself.  It makes it easier to update documentation at
the same time as you are updating code, and makes it significantly
easier to know which documentation syncs with which code.

That being said, I can also see the advantage of having the docs in
markdown or rst or something much simpler to edit than xml.

On 05/18/2011 03:18 PM, Tauren Mills wrote:

> I like the idea of having versioned docs very much. And I also like
> being able to output to html, single-page html, and PDF. However, I'm
> not sure DocBook is the way to go.
>
> Perhaps I'm mistaken, as I've never used DocBook before, but anything
> XML based makes me cringe! Even if there is a nice WYSIWYG editor, I
> can bet that many people wouldn't take the time to find it and use it.
> It seems like this would discourage people from helping with
> documentation.
>
> What about hosting the documentation at github? Github projects can
> have hosted pages that are backed by files in a git repo. And they've
> added a REALLY COOL feature now that lets you view a file, click the
> "Fork and edit this file" button, and edit it right in your browser.
> When you are done, click the "Propose File Changes" button and it will
> automatically submit a pull request. Of course, people can still check
> out the repo and edit locally if they prefer.
>
> If this could be combined with documentation files that are formatted
> in Markdown or some other very easy to use (non-XML) format, it would
> be dead simple to do documentation. In my opinion, this would really
> lower the barrier to entry, which in my mind is half the reason people
> don't contributed to documentation more.
>
> My 2c...
>
> Tauren
>
>
>
> On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <[hidden email]> wrote:
>> We've been using the wiki to write documentation so far.
>>
>> However, I've been having a lot of problems updating documentation to
>> reflect new/upcoming features, resorting to '<= 1.1' and '>= 1.2'
>> section headers, and callouts and such to indicate current vs old vs
>> upcoming features.  Yuck.
>>
>> Many successful open-source projects have moved to a DocBook file
>> format that can be versioned in version control along side code
>> changes (Hibernate, Spring, etc).  Then published documentation for a
>> release coincides with the features in that release.  And they
>> typically provide 3 convenient outputs (html, html-single-page, and
>> PDF).
>>
>> Sonatype has open-sourced (ASL 2.0 I believe) an example documentation
>> project that they use to write their book.  We could use that same
>> project to have a 'refmanual' maven model so that documentation is
>> always sync'd with Shiro's code.
>>
>> 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?
>>
>> Les
>>
>> P.S. if there are concerns about writing DocBook XML, the guys at
>> XMLMind can be contacted for a free license for their XML WYSIWYG
>> editor to do Open-Source work: http://www.xmlmind.com/xmleditor/
>>

Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Les Hazlewood-2
In reply to this post by Tauren Mills
I'm open to any documentation format actually, as long as the
resulting output is pleasant to look at and can be incorporated into
our build.

For example, we'll need the ability to show images, represent callouts
(info, note, warning, etc), show formatted code blocks, preferably
with color-coded syntax.  I've never used Markdown or rst - can they
handle these needs?

Also, I'd like this to be part of our build process to ensure that
this stuff is generated automatically at the time we perform a
release.  Can those other mechanisms be used via a Maven build?

Les

On Wed, May 18, 2011 at 1:18 PM, Tauren Mills <[hidden email]> wrote:

> I like the idea of having versioned docs very much. And I also like
> being able to output to html, single-page html, and PDF. However, I'm
> not sure DocBook is the way to go.
>
> Perhaps I'm mistaken, as I've never used DocBook before, but anything
> XML based makes me cringe! Even if there is a nice WYSIWYG editor, I
> can bet that many people wouldn't take the time to find it and use it.
> It seems like this would discourage people from helping with
> documentation.
>
> What about hosting the documentation at github? Github projects can
> have hosted pages that are backed by files in a git repo. And they've
> added a REALLY COOL feature now that lets you view a file, click the
> "Fork and edit this file" button, and edit it right in your browser.
> When you are done, click the "Propose File Changes" button and it will
> automatically submit a pull request. Of course, people can still check
> out the repo and edit locally if they prefer.
>
> If this could be combined with documentation files that are formatted
> in Markdown or some other very easy to use (non-XML) format, it would
> be dead simple to do documentation. In my opinion, this would really
> lower the barrier to entry, which in my mind is half the reason people
> don't contributed to documentation more.
>
> My 2c...
>
> Tauren
>
>
>
> On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <[hidden email]> wrote:
>> We've been using the wiki to write documentation so far.
>>
>> However, I've been having a lot of problems updating documentation to
>> reflect new/upcoming features, resorting to '<= 1.1' and '>= 1.2'
>> section headers, and callouts and such to indicate current vs old vs
>> upcoming features.  Yuck.
>>
>> Many successful open-source projects have moved to a DocBook file
>> format that can be versioned in version control along side code
>> changes (Hibernate, Spring, etc).  Then published documentation for a
>> release coincides with the features in that release.  And they
>> typically provide 3 convenient outputs (html, html-single-page, and
>> PDF).
>>
>> Sonatype has open-sourced (ASL 2.0 I believe) an example documentation
>> project that they use to write their book.  We could use that same
>> project to have a 'refmanual' maven model so that documentation is
>> always sync'd with Shiro's code.
>>
>> 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?
>>
>> Les
>>
>> P.S. if there are concerns about writing DocBook XML, the guys at
>> XMLMind can be contacted for a free license for their XML WYSIWYG
>> editor to do Open-Source work: http://www.xmlmind.com/xmleditor/
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Tauren Mills
I'm indifferent on if the docs should be in the same source tree or
not. But I don't see why that would make any difference on building
the documentation site.

I'd propose using a plain text format such as markdown, textile, rst,
rdoc, etc. There are many flavors to choose from, each has pros and
cons.
http://stackoverflow.com/questions/34276/markdown-versus-restructuredtext

Also, even though I suggested hosting the docs on github doesn't mean
that you'd have to do this, it would just make it easier to update the
live docs from people's pull requests on github. This begs the
question - should the docs be tied to the maven build process, or
would having live docs be better?

Of course, if Shiro commits have to be done via SVN, then this is less
useful. I see there's a shiro mirror on github, but is that only to
clone the repo easily via git, and not to contribute back? If that's
the case, then having a separate docs repo might be better.

I wish I could provide step-by-step instructions on how to integrate
markdown, etc. with a Maven build process, but I haven't done that
before. The point is that it is much more enjoyable to write in
markdown or similar formats. Some googling produced these possibly
helpful links:

http://buildndeploy.wordpress.com/2011/03/06/generating-pdfs-with-maven-markdown-pandoc-and-htmldoc/
http://codeslife.com/2011/05/05/markdown-is-supported-in-maven-site/

Markdown to HTML can be done on the server or client, and I would also
presume during a build process. Typically syntax color coding is
handled client-side, but there are probably tools to process it server
side. I'm not familiar with them, although this link might prove
useful:
http://www.leancrew.com/all-this/2010/12/new-syntax-highlighting-for-markdown/

Also, it looks like XSLT can be used to generate markdown from HTML,
so I'm guessing the reverse is possible?
http://stackoverflow.com/questions/59557/html-to-markdown-with-java

These suggestions are all a little off-the-cuff and just intended as
food for thought. The ideas would have to be evaluated for how to best
include them in a build process. My intent is to point out that
contributing docs should be dead simple and that providing DocBook
patches might not provide this simplicity.

Tauren


On Wed, May 18, 2011 at 1:45 PM, Les Hazlewood <[hidden email]> wrote:

> I'm open to any documentation format actually, as long as the
> resulting output is pleasant to look at and can be incorporated into
> our build.
>
> For example, we'll need the ability to show images, represent callouts
> (info, note, warning, etc), show formatted code blocks, preferably
> with color-coded syntax.  I've never used Markdown or rst - can they
> handle these needs?
>
> Also, I'd like this to be part of our build process to ensure that
> this stuff is generated automatically at the time we perform a
> release.  Can those other mechanisms be used via a Maven build?
>
> Les
>
> On Wed, May 18, 2011 at 1:18 PM, Tauren Mills <[hidden email]> wrote:
>> I like the idea of having versioned docs very much. And I also like
>> being able to output to html, single-page html, and PDF. However, I'm
>> not sure DocBook is the way to go.
>>
>> Perhaps I'm mistaken, as I've never used DocBook before, but anything
>> XML based makes me cringe! Even if there is a nice WYSIWYG editor, I
>> can bet that many people wouldn't take the time to find it and use it.
>> It seems like this would discourage people from helping with
>> documentation.
>>
>> What about hosting the documentation at github? Github projects can
>> have hosted pages that are backed by files in a git repo. And they've
>> added a REALLY COOL feature now that lets you view a file, click the
>> "Fork and edit this file" button, and edit it right in your browser.
>> When you are done, click the "Propose File Changes" button and it will
>> automatically submit a pull request. Of course, people can still check
>> out the repo and edit locally if they prefer.
>>
>> If this could be combined with documentation files that are formatted
>> in Markdown or some other very easy to use (non-XML) format, it would
>> be dead simple to do documentation. In my opinion, this would really
>> lower the barrier to entry, which in my mind is half the reason people
>> don't contributed to documentation more.
>>
>> My 2c...
>>
>> Tauren
>>
>>
>>
>> On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <[hidden email]> wrote:
>>> We've been using the wiki to write documentation so far.
>>>
>>> However, I've been having a lot of problems updating documentation to
>>> reflect new/upcoming features, resorting to '<= 1.1' and '>= 1.2'
>>> section headers, and callouts and such to indicate current vs old vs
>>> upcoming features.  Yuck.
>>>
>>> Many successful open-source projects have moved to a DocBook file
>>> format that can be versioned in version control along side code
>>> changes (Hibernate, Spring, etc).  Then published documentation for a
>>> release coincides with the features in that release.  And they
>>> typically provide 3 convenient outputs (html, html-single-page, and
>>> PDF).
>>>
>>> Sonatype has open-sourced (ASL 2.0 I believe) an example documentation
>>> project that they use to write their book.  We could use that same
>>> project to have a 'refmanual' maven model so that documentation is
>>> always sync'd with Shiro's code.
>>>
>>> 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?
>>>
>>> Les
>>>
>>> P.S. if there are concerns about writing DocBook XML, the guys at
>>> XMLMind can be contacted for a free license for their XML WYSIWYG
>>> editor to do Open-Source work: http://www.xmlmind.com/xmleditor/
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

kaosko
In reply to this post by Les Hazlewood-2
On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Brian Demers
Another idea is to look at what Atlassian does with doc in confluence:
http://confluence.atlassian.com/display/JIRA043/JIRA+Documentation

They keep multiple versions of the doc in the wiki


On Wed, May 18, 2011 at 6:26 PM, Kalle Korhonen
<[hidden email]>wrote:

> On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <[hidden email]>
> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Les Hazlewood
Administrator
In reply to this post by kaosko
On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
<[hidden email]> wrote:

> On Wed, May 18, 2011 at 12:41 PM, Les Hazlewood <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Les Hazlewood-2
In reply to this post by kaosko
On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
<[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Tauren Mills
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 <[hidden email]>wrote:

> On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
> <[hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Brian Demers
I tried to update the doc this weekend and it took me a while to figure out
how to do it.  The doc located at http://shiro.apache.org/ or readme
https://svn.apache.org/repos/asf/shiro/site-template/README,  do not mention
the confluence site located at:
https://cwiki.apache.org/confluence/display/SHIRO/

Google found it of course, but then I needed to create a new login.

What I am getting at is I think the current site doc is a bit complicated to
update.  I like the look of the Shiro site better then a confluence page,
but it does not have the wiki feel to it.

If we say with the current export functionality, maybe we should add an edit
button that would navigate back to cwiki ? Or a page that describes the
process on the Shrio site?

Any thoughts?





On Thu, May 19, 2011 at 1:49 PM, Tauren Mills <[hidden email]> wrote:

> 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 <[hidden email]
> >wrote:
>
> > On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
> > <[hidden email]> 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
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Les Hazlewood
Administrator
That sounds great to me - I think we'll need to update the page
template to support something like this.

On a side note, although it is evident that this wasn't effective, you
can reach the wiki via:

shiro.apache.org > Contribute > Developer Resources

On Tue, May 24, 2011 at 8:54 AM, Brian Demers <[hidden email]> wrote:

> I tried to update the doc this weekend and it took me a while to figure out
> how to do it.  The doc located at http://shiro.apache.org/ or readme
> https://svn.apache.org/repos/asf/shiro/site-template/README,  do not mention
> the confluence site located at:
> https://cwiki.apache.org/confluence/display/SHIRO/
>
> Google found it of course, but then I needed to create a new login.
>
> What I am getting at is I think the current site doc is a bit complicated to
> update.  I like the look of the Shiro site better then a confluence page,
> but it does not have the wiki feel to it.
>
> If we say with the current export functionality, maybe we should add an edit
> button that would navigate back to cwiki ? Or a page that describes the
> process on the Shrio site?
>
> Any thoughts?
>
>
>
>
>
> On Thu, May 19, 2011 at 1:49 PM, Tauren Mills <[hidden email]> wrote:
>
>> 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 <[hidden email]
>> >wrote:
>>
>> > On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
>> > <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Brian Demers
Good point, now that you point it out, I have no idea how I missed that


On Tue, May 24, 2011 at 2:51 PM, Les Hazlewood <[hidden email]> wrote:

> That sounds great to me - I think we'll need to update the page
> template to support something like this.
>
> On a side note, although it is evident that this wasn't effective, you
> can reach the wiki via:
>
> shiro.apache.org > Contribute > Developer Resources
>
> On Tue, May 24, 2011 at 8:54 AM, Brian Demers <[hidden email]>
> wrote:
> > I tried to update the doc this weekend and it took me a while to figure
> out
> > how to do it.  The doc located at http://shiro.apache.org/ or readme
> > https://svn.apache.org/repos/asf/shiro/site-template/README,  do not
> mention
> > the confluence site located at:
> > https://cwiki.apache.org/confluence/display/SHIRO/
> >
> > Google found it of course, but then I needed to create a new login.
> >
> > What I am getting at is I think the current site doc is a bit complicated
> to
> > update.  I like the look of the Shiro site better then a confluence page,
> > but it does not have the wiki feel to it.
> >
> > If we say with the current export functionality, maybe we should add an
> edit
> > button that would navigate back to cwiki ? Or a page that describes the
> > process on the Shrio site?
> >
> > Any thoughts?
> >
> >
> >
> >
> >
> > On Thu, May 19, 2011 at 1:49 PM, Tauren Mills <[hidden email]>
> wrote:
> >
> >> 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 <[hidden email]
> >> >wrote:
> >>
> >> > On Wed, May 18, 2011 at 3:26 PM, Kalle Korhonen
> >> > <[hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Les Hazlewood-2
Even so, I think your idea is even better - it should be much easier
to contribute to a page than to have to figure out where to navigate
to do so.

On Tue, May 24, 2011 at 2:10 PM, Brian Demers <[hidden email]> wrote:
> Good point, now that you point it out, I have no idea how I missed that
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Tauren Mills
I was just browsing the new documentation section on the
html5boilerplate site and found an example of using github with
Markdown to allow anyone to edit the docs. This is very similar to
what I was suggesting previously. Take a look and see just how easy it
would be for people to contribute:

http://html5boilerplate.com/docs/#Home

Clicking the "Edit this Page" link takes you to a github page with an
editor opened. No yucky xml or html tags to deal with. And they give
you the choice of 9 difference markup languages to use.

This solution is slightly different than what I was proposing since
they are using the github wiki. But it is git-backed and should work
just as well. It also appears to be deployed to their custom website,
not having to reside on a github hosted site.

Food for thought...

Tauren


On Tue, May 24, 2011 at 2:43 PM, Les Hazlewood <[hidden email]> wrote:
> Even so, I think your idea is even better - it should be much easier
> to contribute to a page than to have to figure out where to navigate
> to do so.
>
> On Tue, May 24, 2011 at 2:10 PM, Brian Demers <[hidden email]> wrote:
>> Good point, now that you point it out, I have no idea how I missed that
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Les Hazlewood-2
Hi Tauren,

This is pretty cool - I'd have to ask the PMC and maybe the ASF Board
how this should work though - as I understand it, all ASF content must
be hosted by ASF resources.  I'm not sure how git would/could be used
for something like this.  I.e. if you'd consider git an 'editor', but
the final output is put in our SVN? Not sure...

Does anyone know or have any ideas? Kalle? Alan? Craig?

Cheers,

--
Les Hazlewood
Founder, Katasoft, Inc.
Application Security Products & Professional Apache Shiro Support and Training:
http://www.katasoft.com

On Thu, May 26, 2011 at 3:46 PM, Tauren Mills <[hidden email]> wrote:

> I was just browsing the new documentation section on the
> html5boilerplate site and found an example of using github with
> Markdown to allow anyone to edit the docs. This is very similar to
> what I was suggesting previously. Take a look and see just how easy it
> would be for people to contribute:
>
> http://html5boilerplate.com/docs/#Home
>
> Clicking the "Edit this Page" link takes you to a github page with an
> editor opened. No yucky xml or html tags to deal with. And they give
> you the choice of 9 difference markup languages to use.
>
> This solution is slightly different than what I was proposing since
> they are using the github wiki. But it is git-backed and should work
> just as well. It also appears to be deployed to their custom website,
> not having to reside on a github hosted site.
>
> Food for thought...
>
> Tauren
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Les Hazlewood-2
I didn't mean 'hosted' - more like 'originate from'

On Fri, May 27, 2011 at 10:30 AM, Les Hazlewood <[hidden email]> wrote:

> Hi Tauren,
>
> This is pretty cool - I'd have to ask the PMC and maybe the ASF Board
> how this should work though - as I understand it, all ASF content must
> be hosted by ASF resources.  I'm not sure how git would/could be used
> for something like this.  I.e. if you'd consider git an 'editor', but
> the final output is put in our SVN? Not sure...
>
> Does anyone know or have any ideas? Kalle? Alan? Craig?
>
> Cheers,
>
> --
> Les Hazlewood
> Founder, Katasoft, Inc.
> Application Security Products & Professional Apache Shiro Support and Training:
> http://www.katasoft.com
>
> On Thu, May 26, 2011 at 3:46 PM, Tauren Mills <[hidden email]> wrote:
>> I was just browsing the new documentation section on the
>> html5boilerplate site and found an example of using github with
>> Markdown to allow anyone to edit the docs. This is very similar to
>> what I was suggesting previously. Take a look and see just how easy it
>> would be for people to contribute:
>>
>> http://html5boilerplate.com/docs/#Home
>>
>> Clicking the "Edit this Page" link takes you to a github page with an
>> editor opened. No yucky xml or html tags to deal with. And they give
>> you the choice of 9 difference markup languages to use.
>>
>> This solution is slightly different than what I was proposing since
>> they are using the github wiki. But it is git-backed and should work
>> just as well. It also appears to be deployed to their custom website,
>> not having to reside on a github hosted site.
>>
>> Food for thought...
>>
>> Tauren
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Craig L Russell
In reply to this post by Les Hazlewood-2
The ASF recently converted to a CMS with a home-grown editor with  
markdown for the main Apache site. Other Apache projects can also use  
the infrastructure as well. Contact infra@ for details on how to  
migrate the Shiro site to the new CMS.

Craig

On May 27, 2011, at 10:30 AM, Les Hazlewood wrote:

> Hi Tauren,
>
> This is pretty cool - I'd have to ask the PMC and maybe the ASF Board
> how this should work though - as I understand it, all ASF content must
> be hosted by ASF resources.  I'm not sure how git would/could be used
> for something like this.  I.e. if you'd consider git an 'editor', but
> the final output is put in our SVN? Not sure...
>
> Does anyone know or have any ideas? Kalle? Alan? Craig?
>
> Cheers,
>
> --
> Les Hazlewood
> Founder, Katasoft, Inc.
> Application Security Products & Professional Apache Shiro Support  
> and Training:
> http://www.katasoft.com
>
> On Thu, May 26, 2011 at 3:46 PM, Tauren Mills <[hidden email]>  
> wrote:
>> I was just browsing the new documentation section on the
>> html5boilerplate site and found an example of using github with
>> Markdown to allow anyone to edit the docs. This is very similar to
>> what I was suggesting previously. Take a look and see just how easy  
>> it
>> would be for people to contribute:
>>
>> http://html5boilerplate.com/docs/#Home
>>
>> Clicking the "Edit this Page" link takes you to a github page with an
>> editor opened. No yucky xml or html tags to deal with. And they give
>> you the choice of 9 difference markup languages to use.
>>
>> This solution is slightly different than what I was proposing since
>> they are using the github wiki. But it is git-backed and should work
>> just as well. It also appears to be deployed to their custom website,
>> not having to reside on a github hosted site.
>>
>> Food for thought...
>>
>> Tauren

Craig L Russell
Architect, Oracle
http://db.apache.org/jdo
408 276-5638 mailto:[hidden email]
P.S. A good JDO? O, Gasp!

Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Tauren Mills
Les,

I didn't realize the ASF mandated what tools its projects could use.
That seems counter-productive to me. But if so, perhaps the new CMS
would be the simpler solution for now.

It's a shame that the ASF would choose to limit its projects from
using tools that it does not provide. There are solutions out there
that are improving, simplifying, and streamlining development
processes at breakneck speeds. I believe that projects which embrace
and stay current with these new techniques have a significant
advantages. I worry that ASF projects are becoming looked upon as old
dinosaurs that don't know how to keep up with the cool kids. Do we
really want to be Blackberry wielding developers?
http://gozzip.me/wp-content/uploads/2011/02/iPhone-vs-Android-vs-BlackBerry_large.jpg

Tauren




On Fri, May 27, 2011 at 11:10 AM, Craig L Russell
<[hidden email]> wrote:

> The ASF recently converted to a CMS with a home-grown editor with markdown
> for the main Apache site. Other Apache projects can also use the
> infrastructure as well. Contact infra@ for details on how to migrate the
> Shiro site to the new CMS.
>
> Craig
>
> On May 27, 2011, at 10:30 AM, Les Hazlewood wrote:
>
>> Hi Tauren,
>>
>> This is pretty cool - I'd have to ask the PMC and maybe the ASF Board
>> how this should work though - as I understand it, all ASF content must
>> be hosted by ASF resources.  I'm not sure how git would/could be used
>> for something like this.  I.e. if you'd consider git an 'editor', but
>> the final output is put in our SVN? Not sure...
>>
>> Does anyone know or have any ideas? Kalle? Alan? Craig?
>>
>> Cheers,
>>
>> --
>> Les Hazlewood
>> Founder, Katasoft, Inc.
>> Application Security Products & Professional Apache Shiro Support and
>> Training:
>> http://www.katasoft.com
>>
>> On Thu, May 26, 2011 at 3:46 PM, Tauren Mills <[hidden email]> wrote:
>>>
>>> I was just browsing the new documentation section on the
>>> html5boilerplate site and found an example of using github with
>>> Markdown to allow anyone to edit the docs. This is very similar to
>>> what I was suggesting previously. Take a look and see just how easy it
>>> would be for people to contribute:
>>>
>>> http://html5boilerplate.com/docs/#Home
>>>
>>> Clicking the "Edit this Page" link takes you to a github page with an
>>> editor opened. No yucky xml or html tags to deal with. And they give
>>> you the choice of 9 difference markup languages to use.
>>>
>>> This solution is slightly different than what I was proposing since
>>> they are using the github wiki. But it is git-backed and should work
>>> just as well. It also appears to be deployed to their custom website,
>>> not having to reside on a github hosted site.
>>>
>>> Food for thought...
>>>
>>> Tauren
>
> Craig L Russell
> Architect, Oracle
> http://db.apache.org/jdo
> 408 276-5638 mailto:[hidden email]
> P.S. A good JDO? O, Gasp!
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Versioned Reference Manual

Craig L Russell
Tauren,

Please read my message again.

I'm afraid you have completely misunderstood it.

Craig

On May 27, 2011, at 11:49 AM, Tauren Mills wrote:

> Les,
>
> I didn't realize the ASF mandated what tools its projects could use.
> That seems counter-productive to me. But if so, perhaps the new CMS
> would be the simpler solution for now.
>
> It's a shame that the ASF would choose to limit its projects from
> using tools that it does not provide. There are solutions out there
> that are improving, simplifying, and streamlining development
> processes at breakneck speeds. I believe that projects which embrace
> and stay current with these new techniques have a significant
> advantages. I worry that ASF projects are becoming looked upon as old
> dinosaurs that don't know how to keep up with the cool kids. Do we
> really want to be Blackberry wielding developers?
> http://gozzip.me/wp-content/uploads/2011/02/iPhone-vs-Android-vs-BlackBerry_large.jpg
>
> Tauren
>
>
>
>
> On Fri, May 27, 2011 at 11:10 AM, Craig L Russell
> <[hidden email]> wrote:
>> The ASF recently converted to a CMS with a home-grown editor with  
>> markdown
>> for the main Apache site. Other Apache projects can also use the
>> infrastructure as well. Contact infra@ for details on how to  
>> migrate the
>> Shiro site to the new CMS.
>>
>> Craig
>>
>> On May 27, 2011, at 10:30 AM, Les Hazlewood wrote:
>>
>>> Hi Tauren,
>>>
>>> This is pretty cool - I'd have to ask the PMC and maybe the ASF  
>>> Board
>>> how this should work though - as I understand it, all ASF content  
>>> must
>>> be hosted by ASF resources.  I'm not sure how git would/could be  
>>> used
>>> for something like this.  I.e. if you'd consider git an 'editor',  
>>> but
>>> the final output is put in our SVN? Not sure...
>>>
>>> Does anyone know or have any ideas? Kalle? Alan? Craig?
>>>
>>> Cheers,
>>>
>>> --
>>> Les Hazlewood
>>> Founder, Katasoft, Inc.
>>> Application Security Products & Professional Apache Shiro Support  
>>> and
>>> Training:
>>> http://www.katasoft.com
>>>
>>> On Thu, May 26, 2011 at 3:46 PM, Tauren Mills <[hidden email]>  
>>> wrote:
>>>>
>>>> I was just browsing the new documentation section on the
>>>> html5boilerplate site and found an example of using github with
>>>> Markdown to allow anyone to edit the docs. This is very similar to
>>>> what I was suggesting previously. Take a look and see just how  
>>>> easy it
>>>> would be for people to contribute:
>>>>
>>>> http://html5boilerplate.com/docs/#Home
>>>>
>>>> Clicking the "Edit this Page" link takes you to a github page  
>>>> with an
>>>> editor opened. No yucky xml or html tags to deal with. And they  
>>>> give
>>>> you the choice of 9 difference markup languages to use.
>>>>
>>>> This solution is slightly different than what I was proposing since
>>>> they are using the github wiki. But it is git-backed and should  
>>>> work
>>>> just as well. It also appears to be deployed to their custom  
>>>> website,
>>>> not having to reside on a github hosted site.
>>>>
>>>> Food for thought...
>>>>
>>>> Tauren
>>
>> Craig L Russell
>> Architect, Oracle
>> http://db.apache.org/jdo
>> 408 276-5638 mailto:[hidden email]
>> P.S. A good JDO? O, Gasp!
>>
>>

Craig L Russell
Architect, Oracle
http://db.apache.org/jdo
408 276-5638 mailto:[hidden email]
P.S. A good JDO? O, Gasp!

12