[wildfly-dev] One Doc to Rule Them All

[Brian Stansberry]

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