Re: [wildfly-dev] One Doc to Rule Them All

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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/wildfly-dev > -- - DML _______________________________________________ wildfly-dev mailing list wildfly-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/wildfly-dev