<div dir="ltr">See also <a href="https://opensource.com/article/17/9/modular-documentation">https://opensource.com/article/17/9/modular-documentation</a></div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Nov 9, 2017 at 9:50 AM, Tomaž Cerar <span dir="ltr"><<a href="mailto:tomaz.cerar@gmail.com" target="_blank">tomaz.cerar@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div lang="SL" link="blue" vlink="#954F72"><div class="m_4545643862959498304WordSection1"><p class="MsoNormal"><a href="https://github.com/redhat-documentation/modular-docs" target="_blank">https://github.com/redhat-<wbr>documentation/modular-docs</a></p><p class="MsoNormal"><u></u> <u></u></p><p class="MsoNormal">--</p><p class="MsoNormal">tomaz</p><p class="MsoNormal"><u></u> <u></u></p><div style="border:none;border-top:solid #e1e1e1 1.0pt;padding:3.0pt 0cm 0cm 0cm"><p class="MsoNormal" style="border:none;padding:0cm"><b>From: </b><a href="mailto:brian.stansberry@redhat.com" target="_blank">Brian Stansberry</a><br><b>Sent: </b>četrtek, 09. november 2017 15:28<br><b>To: </b><a href="mailto:tomaz.cerar@gmail.com" target="_blank">Tomaž Cerar</a><br><b>Cc: </b><a href="mailto:bmcwhirt@redhat.com" target="_blank">Bob McWhirter</a>; <a href="mailto:wildfly-dev@lists.jboss.org" target="_blank">wildfly-dev@lists.jboss.org</a></p><div><div class="h5"><br><b>Subject: </b>Re: [wildfly-dev] WildFly asciidoc based documentation</div></div><p></p></div><div><div class="h5"><p class="MsoNormal"><u></u> <u></u></p><div><div><p class="MsoNormal"><u></u> <u></u></p><div><p class="MsoNormal">On Thu, Nov 9, 2017 at 8:19 AM, Tomaž Cerar <<a href="mailto:tomaz.cerar@gmail.com" target="_blank">tomaz.cerar@gmail.com</a>> wrote:</p><blockquote style="border:none;border-left:solid #cccccc 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm"><div><div><p class="MsoNormal">I've updated PR <a href="https://github.com/wildfly/wildfly/pull/10523" target="_blank">https://github.com/wildfly/<wbr>wildfly/pull/10523</a></p><p class="MsoNormal">That brings in converted confluence documentation.</p><p class="MsoNormal">It is synced with todays content in confluence.</p><p class="MsoNormal"> </p><p class="MsoNormal">This is just a start, going forward we should</p><p class="MsoNormal"> </p><ul type="disc"><li class="MsoNormal">Split docs between core & full</li><li class="MsoNormal">Each subsystem could have docs folder that would be than agreggated </li><li class="MsoNormal">Publish docs somewhere. Maybe use GH for start <a href="http://wildfly.github.io/" target="_blank">http://wildfly.github.io/</a></li><li class="MsoNormal">Restrucutre docs into few books instead of what we have now.</li></ul></div></div></blockquote><div><p class="MsoNormal">As we get into this last bit, we should look into the modular stuff Bob mentioned. It sounds like it would mean a large scale rewrite, so if we start doing things that are more than just moving some files around we should consider the bigger picture.</p></div><div><p class="MsoNormal"><u></u> <u></u></p></div><blockquote style="border:none;border-left:solid #cccccc 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-right:0cm"><div><div><p class="MsoNormal"> </p><p class="MsoNormal">--</p><p class="MsoNormal">tomaz</p><p class="MsoNormal"> </p><p class="MsoNormal"> </p><div style="border:none;border-top:solid #e1e1e1 1.0pt;padding:3.0pt 0cm 0cm 0cm"><p class="MsoNormal"><b>From: </b><a href="mailto:bmcwhirt@redhat.com" target="_blank">Bob McWhirter</a><br><b>Sent: </b>četrtek, 09. november 2017 01:48<br><b>To: </b><a href="mailto:brian.stansberry@redhat.com" target="_blank">Brian Stansberry</a><br><b>Cc: </b><a href="mailto:wildfly-dev@lists.jboss.org" target="_blank">wildfly-dev@lists.jboss.org</a><br><b>Subject: </b>Re: [wildfly-dev] WildFly asciidoc based documentation</p></div><div><div><p class="MsoNormal"> </p><div><div><p class="MsoNormal">We have recent used he doc teams “modular documentation templates” and I think they are lovely and also makes the docs team happy. </p></div><div><p class="MsoNormal"> </p></div><div><p class="MsoNormal">Ask your doctor if modular documentation templates are right for you. </p></div><div><p class="MsoNormal"> </p></div><div><p class="MsoNormal">Bob</p></div><p class="MsoNormal"> </p><div><div><p class="MsoNormal">On Wed, Nov 8, 2017 at 12:40 PM Brian Stansberry <<a href="mailto:brian.stansberry@redhat.com" target="_blank">brian.stansberry@redhat.com</a>> wrote:</p></div><blockquote style="border:none;border-left:solid #cccccc 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-top:5.0pt;margin-right:0cm;margin-bottom:5.0pt"><div><p class="MsoNormal">Sounds like a good goal, but I don't think Tomaz should be responsible for correcting all our docs to make them conform. For many of these I doubt the Confluence markup includes relevant metadata that would have allowed that (e.g. that a given literal was a filename, hence [filename]`thename` instead of `thename`. We'd need to assign owners to various pages and have them correct them. An obvious initial owner being the component lead for the component that's most relevant to the page.</p></div><div><p class="MsoNormal"> </p><div><p class="MsoNormal">On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <<a href="mailto:david.lloyd@redhat.com" target="_blank">david.lloyd@redhat.com</a>> wrote:</p><blockquote style="border:none;border-left:solid #cccccc 1.0pt;padding:0cm 0cm 0cm 6.0pt;margin-left:4.8pt;margin-top:5.0pt;margin-right:0cm;margin-bottom:5.0pt"><p class="MsoNormal">I would suggest that we ensure that our produced AsciiDoc files<br>conform to [1] (generated from [2]). Beyond that, I support this<br>initiative wholeheartedly.<br><br>[1] <a href="https://redhat-documentation.github.io/asciidoc-markup-conventions/" target="_blank">https://redhat-documentation.<wbr>github.io/asciidoc-markup-<wbr>conventions/</a><br>[2] <a href="https://github.com/redhat-documentation/asciidoc-markup-conventions" target="_blank">https://github.com/redhat-<wbr>documentation/asciidoc-markup-<wbr>conventions</a></p><div><div><p class="MsoNormal"><br>On Tue, Nov 7, 2017 at 12:06 PM, Brian Stansberry<br><<a href="mailto:brian.stansberry@redhat.com" target="_blank">brian.stansberry@redhat.com</a>> wrote:<br>> Since we're done with WF 11, I think it's time to move forward on this.<br>> There's still some discussion to have about decomposing the docs so the<br>> relevant doc bits are aligned with the feature packs they come from, but I<br>> haven't heard any argument against moving off Confluence and having the docs<br>> included in the source tree. Since we don't have the current docs decomposed<br>> in any way, I see no reason not to go ahead with bringing the docs in<br>> wildfly/wildfly master and then we can deal with decomposition as a later<br>> step.<br>><br>> On Tue, Sep 19, 2017 at 7:58 AM, Tomaž Cerar <<a href="mailto:tomaz.cerar@gmail.com" target="_blank">tomaz.cerar@gmail.com</a>> wrote:<br>>><br>>> Hey guys,<br>>><br>>> TL;DR<br>>> I've converted confluence docs asciidoc [1] [2] ones that will be part of<br>>> WildFly codebase,<br>>> take a look at them and let me know if there are any big issues.<br>>><br>>><br>>> ----<br>>> full version:<br>>><br>>> as most of you already know, I was working on moving our confluence based<br>>> [1] documentation to asciidoc based one.<br>>><br>>> result can be seen at [7] or rendered to html at [8]<br>>><br>>> A good side effect of conversion is that now docs are also browsable<br>>> directly on GitHub.<br>>> For example [2] or [3]<br>>><br>>> Currently I kept same structure as we had in confluence, which in practice<br>>> means<br>>> we have set of "guides" that than have lots of sub pages / includes that<br>>> produce "big" guides.<br>>> Currently such guides are:<br>>> - Admin Guide<br>>> - Developer Guide<br>>> - Getting started guide<br>>> - Getting Started Developing Applications Guide<br>>> - High Availability Guide<br>>> - Extending WildFly guide<br>>> - JavaEE 7(6 actually) Tutorial<br>>> - Elytron security guide<br>>> - quickstarts<br>>> - Testsuite<br>>><br>>> Problem is that some of this guide as such make sense, but not all of them<br>>> do.<br>>> In some cases we have duplicated docs for same thing, in others we content<br>>> in wrong segment.<br>>> For example instead of having all subsystem reference docs under admin<br>>> guide,<br>>> some are under Developer Guide and some even under HA guide.<br>>><br>>> Going forward we should "refactor" docs a bit, so we would end up with 3-4<br>>> high quality guides.<br>>> We should also go trough all docs and remove/update the outdated content.<br>>><br>>> Plan is also to have documentation now part of WildFly codebase.<br>>> So when we would submit PR with new feature, it would also include<br>>> documentation for it as well.<br>>><br>>> Rendered docs can be build as part of our build / release process and can<br>>> be rendered to different formats.<br>>> for example default is HTML [5] or PDF [6]<br>>><br>>> I've send experimental PR to show how docs would fit into WildFly build<br>>> [4]<br>>><br>>> Please take look at current docs and if you have any comments /<br>>> suggestions what we can improve before merging it let me know.<br>>> At this point I've not done much content-wise changes but just conversion<br>>> + formatting ones.<br>>> Content updates can come after this is merged.<br>>><br>>> --<br>>> tomaz<br>>><br>>> [1] <a href="https://docs.jboss.org/author/display/WFLY/Documentation" target="_blank">https://docs.jboss.org/author/<wbr>display/WFLY/Documentation</a><br>>> [2]<br>>> <a href="https://github.com/ctomc/docs-playground/blob/master/admin-guide/Operating_modes.adoc" target="_blank">https://github.com/ctomc/docs-<wbr>playground/blob/master/admin-<wbr>guide/Operating_modes.adoc</a><br>>> [3]<br>>> <a href="https://github.com/ctomc/docs-playground/blob/master/developer-guide/EJB3_Reference_Guide.adoc" target="_blank">https://github.com/ctomc/docs-<wbr>playground/blob/master/<wbr>developer-guide/EJB3_<wbr>Reference_Guide.adoc</a><br>>> [4] <a href="https://github.com/wildfly/wildfly/pull/10523" target="_blank">https://github.com/wildfly/<wbr>wildfly/pull/10523</a><br>>> [5] <a href="https://ctomc.github.io/docs-playground/Admin_Guide.html" target="_blank">https://ctomc.github.io/docs-<wbr>playground/Admin_Guide.html</a><br>>> [6] <a href="https://ctomc.github.io/docs-playground/Admin_Guide.pdf" target="_blank">https://ctomc.github.io/docs-<wbr>playground/Admin_Guide.pdf</a><br>>> [7] <a href="https://github.com/ctomc/docs-playground" target="_blank">https://github.com/ctomc/docs-<wbr>playground</a><br>>> [8] <a href="https://ctomc.github.io/docs-playground/" target="_blank">https://ctomc.github.io/docs-<wbr>playground/</a><br>>><br>>> ______________________________<wbr>_________________<br>>> wildfly-dev mailing list<br>>> <a href="mailto:wildfly-dev@lists.jboss.org" target="_blank">wildfly-dev@lists.jboss.org</a><br>>> <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" target="_blank">https://lists.jboss.org/<wbr>mailman/listinfo/wildfly-dev</a><br>><br>><br>><br>><br>> --<br>> Brian Stansberry<br>> Manager, Senior Principal Software Engineer<br>> Red Hat<br>><br>> ______________________________<wbr>_________________<br>> wildfly-dev mailing list<br>> <a href="mailto:wildfly-dev@lists.jboss.org" target="_blank">wildfly-dev@lists.jboss.org</a><br>> <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" target="_blank">https://lists.jboss.org/<wbr>mailman/listinfo/wildfly-dev</a><br><br><br><br>--</p></div></div><p class="MsoNormal">- DML</p></blockquote></div><p class="MsoNormal"><br><br clear="all"></p><div><p class="MsoNormal"> </p></div><p class="MsoNormal">-- </p><div><div><p class="MsoNormal">Brian Stansberry</p><div><p class="MsoNormal">Manager, Senior Principal Software Engineer</p></div><div><p class="MsoNormal">Red Hat</p></div></div></div></div></blockquote></div></div><p class="MsoNormal" style="margin-left:4.8pt">______________________________<wbr>_________________<br>wildfly-dev mailing list<br><a href="mailto:wildfly-dev@lists.jboss.org" target="_blank">wildfly-dev@lists.jboss.org</a><br><a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" target="_blank">https://lists.jboss.org/<wbr>mailman/listinfo/wildfly-dev</a></p><p class="MsoNormal"> </p></div></div></div></div></blockquote></div><p class="MsoNormal"><br><br clear="all"></p><div><p class="MsoNormal"><u></u> <u></u></p></div><p class="MsoNormal">-- </p><div><div><p class="MsoNormal">Brian Stansberry</p><div><p class="MsoNormal">Manager, Senior Principal Software Engineer</p></div></div></div></div></div><p class="MsoNormal">Red Hat</p><p class="MsoNormal"><u></u> <u></u></p></div></div></div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr">Brian Stansberry<div>Manager, Senior Principal Software Engineer</div><div>Red Hat</div></div></div>
</div>