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 Wed, 18 May 2011 20:18:18 GMT
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 <lhazlewood@apache.org> 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/
>

Mime
View raw message