<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">Right well basically what I am saying is that instead of forking at a specific point in time, which is really what option 2 is about, we just fork when it really becomes necessary, which is likely a major re-architecture.</div><div class=""><br class=""></div><div class="">While it does sound like I am advocating 1, 3 could meet this as well. We can have one link for “WildFly docs” which is always the most current, and if we were using asciidoc, we could have “archived docs”, which are not maintained but there for reference if need be.</div><div class=""><br class=""></div><div class=""><br class=""></div><div><blockquote type="cite" class=""><div class="">On May 13, 2016, at 12:57 PM, James Perkins <<a href="mailto:jperkins@redhat.com" class="">jperkins@redhat.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class="">Yes I agree on both counts that we fork too often and we're likely to update new documentation only. This kind of goes with my first option where we keep it more generic e.g. use WildFly rather than WildFly ${version}.</div><div class="gmail_extra"><br class=""><div class="gmail_quote">On Fri, May 13, 2016 at 10:53 AM, Jason T. Greene <span dir="ltr" class=""><<a href="mailto:jason.greene@redhat.com" target="_blank" class="">jason.greene@redhat.com</a>></span> wrote:<br class=""><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="auto" class=""><div class="">Also, I think it's far more likely developers will update the current documentation than fix old docs. By having a living doc for all versions you ensure that users always have the most accurate information at their disposal.<br class=""></div><div class=""><div class="h5"><div class=""><br class="">On May 13, 2016, at 12:50 PM, Jason T. Greene <<a href="mailto:jason.greene@redhat.com" target="_blank" class="">jason.greene@redhat.com</a>> wrote:<br class=""><br class=""></div><blockquote type="cite" class=""><div class=""><div class="">Just as a general note, no matter how we generate our documentation we can always qualify versions. For example we can say "Since version X.y, blah". </div><div class=""><br class=""></div><div class="">In general software tends to be additive until you hit a major rearchitecture. Currently I think we are forking the documentation too much. </div><div class=""><br class="">On May 12, 2016, at 10:33 PM, James Perkins <<a href="mailto:jperkins@redhat.com" target="_blank" class="">jperkins@redhat.com</a>> wrote:<br class=""><br class=""></div><blockquote type="cite" class=""><div class=""><div dir="ltr" class="">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.<div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">There's a few different ways we could go with this.</div><div class=""><br class=""></div><div class="">Approach 1:</div><div class="">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.</div><div class=""><br class=""></div><div class="">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}+.</div><div class=""><br class=""></div><div class=""><br class=""></div><div class="">Approach 2:</div><div class="">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.</div><div class=""><br class=""></div><div class="">Approach 3</div><div class="">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.</div><div class=""><br class=""></div><div class="">Any other suggestions are welcome.<br class=""><div class=""><br class=""></div><div class="">[1]: <a href="https://docs.jboss.org/author/display/WFLY10/Documentation" target="_blank" class="">https://docs.jboss.org/author/display/WFLY10/Documentation</a><br clear="all" class=""><div class=""><br class=""></div>-- <br class=""><div class=""><div dir="ltr" class=""><div class=""><div dir="ltr" class=""><div class="">James R. Perkins</div><div class="">JBoss by Red Hat</div></div></div></div></div>
</div></div></div>
</div></blockquote><blockquote type="cite" class=""><div class=""><span class="">_______________________________________________</span><br class=""><span class="">wildfly-dev mailing list</span><br class=""><span class=""><a href="mailto:wildfly-dev@lists.jboss.org" target="_blank" class="">wildfly-dev@lists.jboss.org</a></span><br class=""><span class=""><a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" target="_blank" class="">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a></span></div></blockquote></div></blockquote></div></div></div></blockquote></div><br class=""><br clear="all" class=""><div class=""><br class=""></div>-- <br class=""><div class="gmail_signature"><div dir="ltr" class=""><div class=""><div dir="ltr" class=""><div class="">James R. Perkins</div><div class="">JBoss by Red Hat</div></div></div></div></div>
</div>
_______________________________________________<br class="">wildfly-dev mailing list<br class=""><a href="mailto:wildfly-dev@lists.jboss.org" class="">wildfly-dev@lists.jboss.org</a><br class="">https://lists.jboss.org/mailman/listinfo/wildfly-dev</div></blockquote></div><br class=""><div class="">
--<br class="">Jason T. Greene<br class="">WildFly Lead / JBoss EAP Platform Architect<br class="">JBoss, a division of Red Hat
</div>
<br class=""></body></html>