[wildfly-dev] One Doc to Rule Them All

[James Perkins]

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 approach or even
just make it part of the 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>
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
> > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> >
>
> --
> - DML
> _______________________________________________
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wildfly-dev/attachments/20160513/8809ef11/attachment-0001.html