<div dir="ltr">Yeah I think I prefer approach 3 myself. It just might be a lot of work to get there.<div><br></div><div>I was thinking we could either use the gh-pages/<a href="http://github.io">github.io</a> approach or even just make it part of the <a href="http://wildfly.org">wildfly.org</a> [1] repo in a docs subdirectory. I see it being nice in some ways having it on <a href="http://wildfly.org">http://wildfly.org</a>.</div><div><br></div><div>[1]: <a href="https://github.com/wildfly/wildfly.org">https://github.com/wildfly/wildfly.org</a><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd <span dir="ltr"><<a href="mailto:david.lloyd@redhat.com" target="_blank">david.lloyd@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-style:solid;border-left-color:rgb(204,204,204);padding-left:1ex">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>
<div class=""><div class="h5"><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 documentation<br>
> confusing. Reading documentation for WildFly 10 and seeing WildFly 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 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>
</div></div><span class="im">> _______________________________________________<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>
</span><span class=""><font color="#888888">- DML<br>
</font></span><div class=""><div class="h5">_______________________________________________<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>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>James R. Perkins</div><div>JBoss by Red Hat</div></div></div></div></div>
</div></div></div>