I'm all for making our lives easier, and if Markdown will accomplish that, +1
Does it integrate well with our build process? Cheers, Scott On Tue, Sep 13, 2011 at 5:25 PM, Andrew Petro <[email protected]> wrote: > ** > 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 to [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 > > -- 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
