<p dir="ltr">Hi all, <br>
at Hibernate we publish both the blog <a href="http://in.relation.to">in.relation.to</a> and the website <a href="http://hibernate.org">hibernate.org</a> by pushing asciidoc changes to <a href="http://github.com">github.com</a>. </p>
<p dir="ltr">Documentation of each project is built from asciidoc during the project build, and uploaded as part of each release. </p>
<p dir="ltr">A push - including merging a PR - to website or blog will trigger a CI job which updates the websites. We have a "production" and a "staging" branch. </p>
<p dir="ltr">We also converted all our documentation from docbook, and some of our project still convert the asciidoc documentation into docbook during each release automatically to produce the old style PDF (among other formats). </p>
<p dir="ltr">Documentation is indeed broken up in multiple files, then using includes and variables.. It's particularly nice to inject variable values defined as properties in Maven, we can for example print out versions of dependencies and have them rendered correctly at release time. </p>
<p dir="ltr">The website and the blog use Bob's <a href="http://awestruct.org">http://awestruct.org</a></p>
<p dir="ltr">Have a look at our <a href="http://ci.hibernate.org">ci.hibernate.org</a> jobs, or ask us more specific questions we're happy to point to examples of each piece of the puzzle. </p>
<p dir="ltr">It works quite nicely, BUT:<br>
- sometimes I envy your wiki, takes less time to get stuff done. Lower quality though... :P<br>
- rebuilding our blog takes like 15 minutes on good day. That's not great when then you notice yet another typo and have to re-trigger it.. <br>
- the gem dependencies for awestruct tend to have weird system dependencies and break often on Fedora... use Docker. </p>
<p dir="ltr">Sanne<br></p>
<div class="gmail_quote">On 14 May 2016 10:09, "Rostislav Svoboda" <<a href="mailto:rsvoboda@redhat.com">rsvoboda@redhat.com</a>> wrote:<br type="attribution"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I like approach used in JBossWS project<br>
<br>
Latest documentation on Confluence - <a href="https://docs.jboss.org/author/display/JBWS/" rel="noreferrer" target="_blank">https://docs.jboss.org/author/display/JBWS/</a><br>
Older documentation available on <a href="http://docs.jboss.org/jbossws/" rel="noreferrer" target="_blank">http://docs.jboss.org/jbossws/</a> - e.g. <a href="http://docs.jboss.org/jbossws/5.1.0.Final/" rel="noreferrer" target="_blank">http://docs.jboss.org/jbossws/5.1.0.Final/</a><br>
<br>
Rostislav<br>
<br>
----- Original Message -----<br>
> I've looked for a few tools, but hadn't seen this one yet. Looks kind of<br>
> promising though. If I could figure out how to export the docs to DocBook<br>
> I'd test it :)<br>
><br>
> On Fri, May 13, 2016 at 1:26 PM, Brian Stansberry <<br>
> <a href="mailto:brian.stansberry@redhat.com">brian.stansberry@redhat.com</a> > wrote:<br>
><br>
><br>
> Has anyone used a good docbook to asciidoc converter, e.g. the docbookrx<br>
> discussed at [1] or the O'Reilly thing at [2]?<br>
><br>
> If we can't have some sort of reasonable conversion it's hard to imagine<br>
> us making the move.<br>
><br>
> [1]<br>
> <a href="https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/" rel="noreferrer" target="_blank">https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/</a><br>
><br>
> [2] <a href="https://github.com/oreillymedia/docbook2asciidoc" rel="noreferrer" target="_blank">https://github.com/oreillymedia/docbook2asciidoc</a><br>
><br>
> On 5/13/16 10:46 AM, James Perkins wrote:<br>
> > Yeah I think I prefer approach 3 myself. It just might be a lot of work<br>
> > to get there.<br>
> ><br>
> > I was thinking we could either use the gh-pages/ <a href="http://github.io" rel="noreferrer" target="_blank">github.io</a><br>
> > < <a href="http://github.io" rel="noreferrer" target="_blank">http://github.io</a> > approach or even just make it part of the <a href="http://wildfly.org" rel="noreferrer" target="_blank">wildfly.org</a><br>
> > < <a href="http://wildfly.org" rel="noreferrer" target="_blank">http://wildfly.org</a> > [1] repo in a docs subdirectory. I see it being<br>
> > nice in some ways having it on <a href="http://wildfly.org" rel="noreferrer" target="_blank">http://wildfly.org</a> .<br>
> ><br>
> > [1]: <a href="https://github.com/wildfly/wildfly.org" rel="noreferrer" target="_blank">https://github.com/wildfly/wildfly.org</a><br>
> ><br>
> > On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd < <a href="mailto:david.lloyd@redhat.com">david.lloyd@redhat.com</a><br>
> > <mailto: <a href="mailto:david.lloyd@redhat.com">david.lloyd@redhat.com</a> >> wrote:<br>
> ><br>
> > I like approach 3, assuming that it'll move in to e.g. GitHub. If<br>
> > there's an update to a doc, it's a lot easier to backport using git than<br>
> > Confluence. Less chance of old docs getting abandoned, and easier for<br>
> > users to contribute fixes and updates if they can just open a PR for<br>
> > each affected version. We're already reasonably well-trained to deal<br>
> > with old branches.<br>
> ><br>
> > I don't know how we'd organize it though; I've never done multi-document<br>
> > things using asciidoc, and also we'd have to publish it somehow<br>
> > (preferably in an automated manner).<br>
> ><br>
> > On 05/12/2016 10:32 PM, James Perkins wrote:<br>
> > > I've been reading the WildFly documentation [1] quite a bit lately and<br>
> > > noticing a lot of issues. Sometimes it references WildFly 8 in the<br>
> > > WildFly 10 (or 9) documentation. Sometimes it references JBoss AS 7.<br>
> > > Links take you to old documentation, e.g. a WFLY10 doc takes you to a<br>
> > > page for WFLY8. Sometimes documentation is just plain out of date<br>
> > > referencing behavior that has possibly been removed or replaced by<br>
> > > something better.<br>
> > ><br>
> > > This has happened because we keep copying the documentation over each<br>
> > > time we have a new version. Overall this makes sense as a lot of it<br>
> > > doesn't need to be changed. However it leaves reading the<br>
> > documentation<br>
> > > confusing. Reading documentation for WildFly 10 and seeing WildFly<br>
> > 8 in<br>
> > > the text with a link for AS72 isn't very user friendly as I'm sure we<br>
> > > can all agree.<br>
> > ><br>
> > > There's a few different ways we could go with this.<br>
> > ><br>
> > > Approach 1:<br>
> > > One, probably the easiest, is to use a single confluence project. We'd<br>
> > > need to remove the version numbers from the text, which I think we<br>
> > > should do anyway. Instead of referencing WildFly 10 we just<br>
> > reference it<br>
> > > as WildFly.<br>
> > ><br>
> > > An issue I can think of with this approach is some how annotating or<br>
> > > referencing that parts of the documentation only work with ${version}.<br>
> > > For example new features would have to be noted they only work with<br>
> > > ${version}+.<br>
> > ><br>
> > ><br>
> > > Approach 2:<br>
> > > Essentially he same as approach 1 only do allow different Confluence<br>
> > > projects for the different Java EE target version. So WIldFly 8, 9 and<br>
> > > 10 would all be documented under something like WFLYEE7.<br>
> > ><br>
> > > Approach 3<br>
> > > Switch to using something like asciidoc which can use variables and<br>
> > > generate links to the correct content. While this approach is probably<br>
> > > takes the most work up front, it seems like like it would be easier to<br>
> > > maintain between releases.<br>
> > ><br>
> > > Any other suggestions are welcome.<br>
> > ><br>
> > > [1]: <a href="https://docs.jboss.org/author/display/WFLY10/Documentation" rel="noreferrer" target="_blank">https://docs.jboss.org/author/display/WFLY10/Documentation</a><br>
> > ><br>
> > > --<br>
> > > James R. Perkins<br>
> > > JBoss by Red Hat<br>
> > ><br>
> > ><br>
> > > _______________________________________________<br>
> > > wildfly-dev mailing list<br>
> > > <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a> <mailto: <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a> ><br>
> > > <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
> > ><br>
> ><br>
> > --<br>
> > - DML<br>
> > _______________________________________________<br>
> > wildfly-dev mailing list<br>
> > <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a> <mailto: <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a> ><br>
> > <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
> ><br>
> ><br>
> ><br>
> ><br>
> > --<br>
> > James R. Perkins<br>
> > JBoss by Red Hat<br>
> ><br>
> ><br>
> > _______________________________________________<br>
> > wildfly-dev mailing list<br>
> > <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
> > <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
> ><br>
><br>
><br>
> --<br>
> Brian Stansberry<br>
> Senior Principal Software Engineer<br>
> JBoss by Red Hat<br>
> _______________________________________________<br>
> wildfly-dev mailing list<br>
> <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
> <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
><br>
><br>
><br>
> --<br>
> James R. Perkins<br>
> JBoss by Red Hat<br>
><br>
> _______________________________________________<br>
> wildfly-dev mailing list<br>
> <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
> <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
_______________________________________________<br>
wildfly-dev mailing list<br>
<a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br>
</blockquote></div>