<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="">Who is hosting the gitbook stuff?<div class=""><br class=""></div><div class="">Lazy question I suspect, but I promise I poked around a bit first and it wasn’t completely obvious. :)</div><div class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jul 25, 2016, at 1:46 PM, Bob McWhirter <<a href="mailto:bmcwhirt@redhat.com" class="">bmcwhirt@redhat.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class="">I’ve been quite pleased with GitBook.<div class=""><br class=""></div><div class="">I’ve not worked with git branches with it, but it does work with commits (and occasionally with tags, but sometimes I’ve failed to make them work).</div><div class=""><br class=""></div><div class="">Basically, every commit produces a new published site, and you can ref any sha1 (or tag, sometimes).</div><div class=""><br class=""></div><div class="">So we keep the repository HEAD as “living” on-going document.</div><div class=""><br class=""></div><div class="">At each release, we tag and then reference that SHA1 for that release’s version of the docs.</div><div class=""><br class=""></div><div class="">See</div><div class=""><br class=""></div><div class=""><a href="http://wildfly-swarm.io/documentation/" class="">http://wildfly-swarm.io/documentation/</a><br class=""></div><div class=""><br class=""></div><div class="">We use AsciiDoc but you can use Markdown also and make that choice on a per-chapter basis.</div><div class=""><br class=""></div><div class="">Additionally, there is a 100% local toolchain, so you can work locally with your favorite editor and see the build in real-time.</div><div class=""><br class=""></div><div class="">Plus, there’s a “native” editor, which is basically a local version of the online editor, based upon Chrome. I don’t love it, especially since they took away my vi keybindings.</div><div class=""><br class=""></div><div class="">It also supports plugins, which we haven’t really explored yet, but they’re just node.js packages from npm.</div><div class=""><br class=""></div><div class="">I also talked Stian/Bill into GitBook for Keycloak.</div><div class=""><br class=""></div><div class="">Another benefit: it doesn’t take 45 seconds to load a page you find via Google because it’s based on a <a href="http://jboss.org" class="">jboss.org</a>-hosted Confluence.</div><div class=""><br class=""></div><div class="">-Bob</div><div class=""><br class=""></div></div><div class="gmail_extra"><br class=""><div class="gmail_quote">On Mon, Jul 25, 2016 at 1:40 PM, James Perkins <span dir="ltr" class=""><<a href="mailto:jperkins@redhat.com" target="_blank" class="">jperkins@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="ltr" class="">Just one more follow as Tomaz mentioned to me, another option would be <a href="https://www.gitbook.com/" target="_blank" class="">https://www.gitbook.com/</a>. Both WildFly Swarm [1] and JBeret [2] use it.<div class=""><br class=""></div><div class="">[1]: <a href="https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/" target="_blank" class="">https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/</a></div><div class="">[2]: <a href="https://jberet.gitbooks.io/jberet-user-guide/content/" target="_blank" class="">https://jberet.gitbooks.io/jberet-user-guide/content/</a></div></div><div class="HOEnZb"><div class="h5"><div class="gmail_extra"><br class=""><div class="gmail_quote">On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <span dir="ltr" class=""><<a href="mailto:jperkins@redhat.com" target="_blank" class="">jperkins@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="ltr" class="">Thanks for bringing this back up Brian. I was just about to do the same :)<div class=""><br class=""></div><div class="">The only idea I'm personally opposed to is the "fork for every release" Though thinking of it as a live doc where we snapshot it for a release is not a bad idea. We could just have a WFLY project that we snapshot for every release. We just need to be careful about using versioning when writing the docs, unless it's a "Since WIldFly whatever" type of thing. We just want to avoid the "In WildFly x".</div><div class=""><br class=""></div><div class="">With regards to the linking problem, I'm not sure if we (myself included) are just linking incorrectly between documents or it's just a limitation of Confluence. It looks like most links are done like [WFLY8:Implicit module dependencies for deployments]. I noticed some don't have the "WFLY${version}" prefix so maybe that's the way to go. When you use the linking function in confluence it adds the doc reference to the link which could be part of the problem.</div><div class=""><br class=""></div><div class="">There are also docs that just point to old information. Like the main page references Java EE 6 getting started [1]. The Some pages are just dead too [2]. In some places, I tried to fix the ones I found in the WFLY10 docs, it just references the wrong version of WildFly. A lot of XML references too which likely point to older namespaces, maybe not a huge deal though.</div><div class=""><br class=""></div><div class="">Overall they're not bad. They just need a little TLC. I do think too there is probably some bigger chunks we can get rid of like a lot of the quickstart section since we have it all on GitHub. Also subsystem references could be replaced with WildScribe.</div><div class=""><br class=""></div><div class="">Anyway, I'm up for anything that allows the documentation to be consistent, easy to write and easy to use. The main attraction for me to asciidoc is being able to use git for versioning as well as being able to use variables. I don't however know how well asciidoc deals with multiple documents and combining them together.</div><div class=""><br class=""></div><div class="">Regardless of the direction I'm willing to put some time into fixing/updating it. I just think before we invest any time we make a firm decision on the direction we want to go.</div><div class=""><br class=""></div><div class=""><br class=""></div><div class="">[1]: <a href="https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-DeveloperGuides" target="_blank" class="">https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-DeveloperGuides</a><br class=""></div><div class="">[2]: <a href="https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+Recommended+Practices" target="_blank" class="">https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+Recommended+Practices</a></div></div><div class=""><div class=""><div class="gmail_extra"><br class=""><div class="gmail_quote">On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <span dir="ltr" class=""><<a href="mailto:brian.stansberry@redhat.com" target="_blank" class="">brian.stansberry@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 style="word-wrap:break-word" class="">So what are we going to do about this?<div class=""><br class=""></div><div class="">We’ve now reached the point where we need to start generating documentation for WildFly 11. And we’re beginning to require devs, at least those working for Red Hat, to write some sort of community doc as part of getting RFEs resolved. So docs infrastructure issue are beginning to impact our ability to get code changes in.</div><div class=""><br class=""></div><div class="">My 2 cents: an asciidoctor and git based approach sounds good, but unless we have resources available to make it happen quickly basically starting from today, we need to devise a strategy based on continuing to use confluence.</div><div class=""><br class=""></div><div class="">The biggest problem I saw in James’ original post was "Links take you to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.” If that’s an inherent problem in cloning docs it’s hard to deal with. Having a living document isn’t so hard; you just write as if it’s a living doc and say things like “Since WildFly 10” etc. But if you can’t snapshot the living doc for a release without creating a lot of bad links, that’s a problem.</div><div class=""><br class=""><div class=""><blockquote type="cite" class=""><div class=""><div class=""><div class="">On May 12, 2016, at 10:32 PM, James Perkins <<a href="mailto:jperkins@redhat.com" target="_blank" class="">jperkins@redhat.com</a>> wrote:</div><br class=""></div></div><div class=""><div 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></div><span class="">
_______________________________________________<br class="">wildfly-dev mailing list<br class=""><a href="mailto:wildfly-dev@lists.jboss.org" target="_blank" class="">wildfly-dev@lists.jboss.org</a><br 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><span class=""><font color="#888888" class=""><br class=""><div class="">
<div class=""><span style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal;background-color:rgb(253,253,253)" class="">--</span><span style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal;background-color:rgb(253,253,253)" class=""> </span><br style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal" class=""><span style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal;background-color:rgb(253,253,253)" class="">Brian Stansberry</span><br style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal" class=""><span style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal;background-color:rgb(253,253,253)" class="">Manager, Senior Principal Software Engineer</span><br style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal" class=""><span style="color:rgb(51,51,51);font-family:monospace;font-size:13.3333px;line-height:normal;background-color:rgb(253,253,253)" class="">JBoss by Red Hat</span></div><div class=""><br class=""></div><br class="">
</div>
<br class=""></font></span></div></div></blockquote></div><br class=""><br clear="all" class=""><div class=""><br class=""></div>-- <br class=""><div data-smartmail="gmail_signature" 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></blockquote></div><br class=""><br clear="all" class=""><div class=""><br class=""></div>-- <br class=""><div data-smartmail="gmail_signature" 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><br class="">_______________________________________________<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="">
<a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank" class="">https://lists.jboss.org/mailman/listinfo/wildfly-dev</a><br class=""></blockquote></div><br class=""></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="">
<div class=""><span style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1; background-color: rgb(253, 253, 253);" class="">--</span><span style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1; background-color: rgb(253, 253, 253);" class=""> </span><br style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1;" class=""><span style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1; background-color: rgb(253, 253, 253);" class="">Brian Stansberry</span><br style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1;" class=""><span style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1; background-color: rgb(253, 253, 253);" class="">Manager, Senior Principal Software Engineer</span><br style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1;" class=""><span style="color: rgb(51, 51, 51); font-family: monospace; font-size: 13.3333px; font-variant-ligatures: normal; font-variant-position: normal; font-variant-numeric: normal; font-variant-alternates: normal; font-variant-east-asian: normal; line-height: normal; widows: 1; background-color: rgb(253, 253, 253);" class="">JBoss by Red Hat</span></div><div class=""><br class=""></div><br class="Apple-interchange-newline">
</div>
<br class=""></div></body></html>