[wildfly-dev] One Doc to Rule Them All

Sat May 14 05:08:57 EDT 2016

I like approach used in JBossWS project

Latest documentation on Confluence - https://docs.jboss.org/author/display/JBWS/
Older documentation available on http://docs.jboss.org/jbossws/ - e.g. http://docs.jboss.org/jbossws/5.1.0.Final/ 

Rostislav

----- Original Message -----
> I've looked for a few tools, but hadn't seen this one yet. Looks kind of
> promising though. If I could figure out how to export the docs to DocBook
> I'd test it :)
> 
> On Fri, May 13, 2016 at 1:26 PM, Brian Stansberry <
> brian.stansberry at redhat.com > wrote:
> 
> 
> Has anyone used a good docbook to asciidoc converter, e.g. the docbookrx
> discussed at [1] or the O'Reilly thing at [2]?
> 
> If we can't have some sort of reasonable conversion it's hard to imagine
> us making the move.
> 
> [1]
> https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/
> 
> [2] https://github.com/oreillymedia/docbook2asciidoc
> 
> On 5/13/16 10:46 AM, James Perkins wrote:
> > Yeah I think I prefer approach 3 myself. It just might be a lot of work
> > to get there.
> > 
> > I was thinking we could either use the gh-pages/ github.io
> > < http://github.io > approach or even just make it part of the wildfly.org
> > < http://wildfly.org > [1] repo in a docs subdirectory. I see it being
> > nice in some ways having it on http://wildfly.org .
> > 
> > [1]: https://github.com/wildfly/wildfly.org
> > 
> > On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd < david.lloyd at redhat.com
> > <mailto: david.lloyd at redhat.com >> wrote:
> > 
> > I like approach 3, assuming that it'll move in to e.g. GitHub. If
> > there's an update to a doc, it's a lot easier to backport using git than
> > Confluence. Less chance of old docs getting abandoned, and easier for
> > users to contribute fixes and updates if they can just open a PR for
> > each affected version. We're already reasonably well-trained to deal
> > with old branches.
> > 
> > I don't know how we'd organize it though; I've never done multi-document
> > things using asciidoc, and also we'd have to publish it somehow
> > (preferably in an automated manner).
> > 
> > On 05/12/2016 10:32 PM, James Perkins wrote:
> > > I've been reading the WildFly documentation [1] quite a bit lately and
> > > noticing a lot of issues. Sometimes it references WildFly 8 in the
> > > WildFly 10 (or 9) documentation. Sometimes it references JBoss AS 7.
> > > Links take you to old documentation, e.g. a WFLY10 doc takes you to a
> > > page for WFLY8. Sometimes documentation is just plain out of date
> > > referencing behavior that has possibly been removed or replaced by
> > > something better.
> > > 
> > > This has happened because we keep copying the documentation over each
> > > time we have a new version. Overall this makes sense as a lot of it
> > > doesn't need to be changed. However it leaves reading the
> > documentation
> > > confusing. Reading documentation for WildFly 10 and seeing WildFly
> > 8 in
> > > the text with a link for AS72 isn't very user friendly as I'm sure we
> > > can all agree.
> > > 
> > > There's a few different ways we could go with this.
> > > 
> > > Approach 1:
> > > One, probably the easiest, is to use a single confluence project. We'd
> > > need to remove the version numbers from the text, which I think we
> > > should do anyway. Instead of referencing WildFly 10 we just
> > reference it
> > > as WildFly.
> > > 
> > > An issue I can think of with this approach is some how annotating or
> > > referencing that parts of the documentation only work with ${version}.
> > > For example new features would have to be noted they only work with
> > > ${version}+.
> > > 
> > > 
> > > Approach 2:
> > > Essentially he same as approach 1 only do allow different Confluence
> > > projects for the different Java EE target version. So WIldFly 8, 9 and
> > > 10 would all be documented under something like WFLYEE7.
> > > 
> > > Approach 3
> > > Switch to using something like asciidoc which can use variables and
> > > generate links to the correct content. While this approach is probably
> > > takes the most work up front, it seems like like it would be easier to
> > > maintain between releases.
> > > 
> > > Any other suggestions are welcome.
> > > 
> > > [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
> > > 
> > > --
> > > James R. Perkins
> > > JBoss by Red Hat
> > > 
> > > 
> > > _______________________________________________
> > > wildfly-dev mailing list
> > > wildfly-dev at lists.jboss.org <mailto: wildfly-dev at lists.jboss.org >
> > > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> > > 
> > 
> > --
> > - DML
> > _______________________________________________
> > wildfly-dev mailing list
> > wildfly-dev at lists.jboss.org <mailto: wildfly-dev at lists.jboss.org >
> > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> > 
> > 
> > 
> > 
> > --
> > James R. Perkins
> > JBoss by Red Hat
> > 
> > 
> > _______________________________________________
> > wildfly-dev mailing list
> > wildfly-dev at lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> > 
> 
> 
> --
> Brian Stansberry
> Senior Principal Software Engineer
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
> 
> 
> 
> --
> James R. Perkins
> JBoss by Red Hat
> 
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev