Folks, DocBook continues to have potential, but documenting XML in XML gets rough fast. Bill Thompson suggested a second look at Pro Git <https://github.com/progit/progit> for inspiration. It's a book <http://progit.org/book/> about Git written in Markdown <http://daringfireball.net/projects/markdown/>.
Pro Git proves that it's possible to author and manage book-looking documentation in Markdown. Here's a stab at porting <https://github.com/apetro/CAS-Documentation> all of the DocBookified CAS manual documentation <https://github.com/Jasig/cas/tree/master/cas-server-documentation> over to Markdown and the PDF generated from that source <https://github.com/downloads/apetro/CAS-Documentation/casmanual.en.pdf>. GitHub's built-in Markdown support is also nice. This <https://github.com/apetro/CAS-Documentation/blob/master/en/07-services-management/07-chapter07.markdown> has pleasant automatic formatting absent here <https://github.com/Jasig/cas/blob/master/cas-server-documentation/src/docbkx/services-management.xml>. But even without cute Github tricks, I'm concerned that, as source, XML looks like this in Docbook source XML: <programlisting> <sec:user-service id="userDetailsService"> <sec:user name="some_trusted_username" password="notused" authorities="ROLE_ADMIN" /> <sec:user name="another_trusted_username" password="notused" authorities="ROLE_ADMIN" /> </sec:user-service> </programlisting> Contrastingly, it looks like this in Markdown: <sec:user-service id="userDetailsService"> <sec:user name="some_trusted_username" password="notused" authorities="ROLE_ADMIN" /> <sec:user name="another_trusted_username" password="notused" authorities="ROLE_ADMIN" /> </sec:user-service> It's a lot more pleasant to read and write the source of the documentation in the latter. So, what problems are we trying to solve with a documentation reboot: 1) Produce and maintain documentation specific to specific versions / branches of CAS server development. Less with the three different ways of doing everything depending on what version we're talking about, and more with documentation maintained in source control with the code doing its best to document that branch of the code. Using source control should help make merging / diffing across branches of documentation feasible. 2) Separate the formal part-of-the-product documentation from the less-formal community-contributed documentation. There have been good contributions in the wiki and lots of sharing -- and that's a good thing. That's what wikis are for. But it's a bit of a mess and it's hard to get a handle on, what's the documentation of the product that's being collaboratively developed in the course of the product development process, vs what's a great external contribution that isn't documenting CAS-as-product. 3) Yet, keep barrier to entry to documentation contribution low. That the documentation's in source control rather than in Confluence shouldn't mean that only committers ever write documentation. Au contraire, tracking in source control via github should welcome forks and pull requests and so forth. Given that, I figure Markdown is a more promising direction. It's just an easier format for authoring, not having to escape XML, and the Github support means that you can fork the repo, edit a page *in your web browser*, and post a pull request to get your change back into the blessed repo, so github's attempt to mostly render the Markdown is adding quite a bit of value. The Markdown documentation prototype isn't perfect, just as the DocBook prototype isn't perfect either. In particular, image handling looks problematic, and the borrowed-from-pro-git process for producing a PDF is pretty heroic. On the other hand, images in DocBook aren't that much fun either. But since Pro Git is successfully working through this pain, I expect CAS can work through this too -- and it seems wiser to accept pain in implementing the post-authoring automation in order to get lower barrier to entry to edit the documentation. All that said, format isn't the most important thing here. In principle we could succeed with Confluence. Or DocBook. Or Markdown. By far the most important factor is, what are CAS developers willing to work on? All of the value is in the content. So, what looks promising? Which direction to go forward with? Andrew On 08/31/2011 09:43 AM, Andrew Petro wrote: > Folks, > > I've some incremental progress on the rebirth of the more-formal CAS > server manual documentation as DocBook. > > Blog post with files posted > <http://www.unicon.net/content/early-progress-new-docbookified-jasig-cas-server-manual> > > thereby avoiding sending attachments to list. > > It clearly needs a lot more work, but is roughly follows the outline > of and slurps in the content from Marvin's new user manual outline > <https://wiki.jasig.org/display/CASUM/User+Manual> and partially > resolves the image inclusion issues that were blocking this effort as > of the Jasig conference. > > > Feedback and collaboration welcome. > > Andrew > > > -- > You are currently subscribed [email protected] > <mailto:[email protected]> as: [email protected] > To unsubscribe, change settings or access archives, see > http://www.ja-sig.org/wiki/display/JSG/cas-dev -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/cas-dev
