<div dir="ltr">Sounds like a good goal, but I don&#39;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&#39;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&#39;s most relevant to the page.</div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <span dir="ltr">&lt;<a href="mailto:david.lloyd@redhat.com" target="_blank">david.lloyd@redhat.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">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/" rel="noreferrer" 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" rel="noreferrer" target="_blank">https://github.com/redhat-<wbr>documentation/asciidoc-markup-<wbr>conventions</a><br>
<div><div class="h5"><br>
On Tue, Nov 7, 2017 at 12:06 PM, Brian Stansberry<br>
&lt;<a href="mailto:brian.stansberry@redhat.com">brian.stansberry@redhat.com</a>&gt; wrote:<br>
&gt; Since we&#39;re done with WF 11, I think it&#39;s time to move forward on this.<br>
&gt; There&#39;s still some discussion to have about decomposing the docs so the<br>
&gt; relevant doc bits are aligned with the feature packs they come from, but I<br>
&gt; haven&#39;t heard any argument against moving off Confluence and having the docs<br>
&gt; included in the source tree. Since we don&#39;t have the current docs decomposed<br>
&gt; in any way, I see no reason not to go ahead with bringing the docs in<br>
&gt; wildfly/wildfly master and then we can deal with decomposition as a later<br>
&gt; step.<br>
&gt;<br>
&gt; On Tue, Sep 19, 2017 at 7:58 AM, Tomaž Cerar &lt;<a href="mailto:tomaz.cerar@gmail.com">tomaz.cerar@gmail.com</a>&gt; wrote:<br>
&gt;&gt;<br>
&gt;&gt; Hey guys,<br>
&gt;&gt;<br>
&gt;&gt; TL;DR<br>
&gt;&gt; I&#39;ve converted confluence docs asciidoc [1] [2] ones that will be part of<br>
&gt;&gt; WildFly codebase,<br>
&gt;&gt; take a look at them and let me know if there are any big issues.<br>
&gt;&gt;<br>
&gt;&gt;<br>
&gt;&gt; ----<br>
&gt;&gt; full version:<br>
&gt;&gt;<br>
&gt;&gt; as most of you already know, I was working on moving our confluence based<br>
&gt;&gt; [1] documentation to asciidoc based one.<br>
&gt;&gt;<br>
&gt;&gt; result can be seen at [7] or rendered to html at [8]<br>
&gt;&gt;<br>
&gt;&gt; A good side effect of conversion is that now docs are also browsable<br>
&gt;&gt; directly on GitHub.<br>
&gt;&gt; For example [2] or [3]<br>
&gt;&gt;<br>
&gt;&gt; Currently I kept same structure as we had in confluence, which in practice<br>
&gt;&gt; means<br>
&gt;&gt; we have set of &quot;guides&quot; that than have lots of sub pages / includes that<br>
&gt;&gt; produce &quot;big&quot; guides.<br>
&gt;&gt; Currently such guides are:<br>
&gt;&gt; - Admin Guide<br>
&gt;&gt; - Developer Guide<br>
&gt;&gt; - Getting started guide<br>
&gt;&gt; - Getting Started Developing Applications Guide<br>
&gt;&gt; - High Availability Guide<br>
&gt;&gt; - Extending WildFly guide<br>
&gt;&gt; - JavaEE 7(6 actually) Tutorial<br>
&gt;&gt; - Elytron security guide<br>
&gt;&gt; - quickstarts<br>
&gt;&gt; - Testsuite<br>
&gt;&gt;<br>
&gt;&gt; Problem is that some of this guide as such make sense, but not all of them<br>
&gt;&gt; do.<br>
&gt;&gt; In some cases we have duplicated docs for same thing, in others we content<br>
&gt;&gt; in wrong segment.<br>
&gt;&gt; For example instead of having all subsystem reference docs under admin<br>
&gt;&gt; guide,<br>
&gt;&gt; some are under Developer Guide and some even under HA guide.<br>
&gt;&gt;<br>
&gt;&gt; Going forward we should &quot;refactor&quot; docs a bit, so we would end up with 3-4<br>
&gt;&gt; high quality guides.<br>
&gt;&gt; We should also go trough all docs and remove/update the outdated content.<br>
&gt;&gt;<br>
&gt;&gt; Plan is also to have documentation now part of WildFly codebase.<br>
&gt;&gt; So when we would submit PR with new feature, it would also include<br>
&gt;&gt; documentation for it as well.<br>
&gt;&gt;<br>
&gt;&gt; Rendered docs can be build as part of our build / release process and can<br>
&gt;&gt; be rendered to different formats.<br>
&gt;&gt; for example default is HTML [5] or PDF [6]<br>
&gt;&gt;<br>
&gt;&gt; I&#39;ve send experimental PR to show how docs would fit into WildFly build<br>
&gt;&gt; [4]<br>
&gt;&gt;<br>
&gt;&gt; Please take look at current docs and if you have any comments /<br>
&gt;&gt; suggestions what we can improve before merging it let me know.<br>
&gt;&gt; At this point I&#39;ve not done much content-wise changes but just conversion<br>
&gt;&gt; + formatting ones.<br>
&gt;&gt; Content updates can come after this is merged.<br>
&gt;&gt;<br>
&gt;&gt; --<br>
&gt;&gt; tomaz<br>
&gt;&gt;<br>
&gt;&gt; [1] <a href="https://docs.jboss.org/author/display/WFLY/Documentation" rel="noreferrer" target="_blank">https://docs.jboss.org/author/<wbr>display/WFLY/Documentation</a><br>
&gt;&gt; [2]<br>
&gt;&gt; <a href="https://github.com/ctomc/docs-playground/blob/master/admin-guide/Operating_modes.adoc" rel="noreferrer" target="_blank">https://github.com/ctomc/docs-<wbr>playground/blob/master/admin-<wbr>guide/Operating_modes.adoc</a><br>
&gt;&gt; [3]<br>
&gt;&gt; <a href="https://github.com/ctomc/docs-playground/blob/master/developer-guide/EJB3_Reference_Guide.adoc" rel="noreferrer" target="_blank">https://github.com/ctomc/docs-<wbr>playground/blob/master/<wbr>developer-guide/EJB3_<wbr>Reference_Guide.adoc</a><br>
&gt;&gt; [4] <a href="https://github.com/wildfly/wildfly/pull/10523" rel="noreferrer" target="_blank">https://github.com/wildfly/<wbr>wildfly/pull/10523</a><br>
&gt;&gt; [5] <a href="https://ctomc.github.io/docs-playground/Admin_Guide.html" rel="noreferrer" target="_blank">https://ctomc.github.io/docs-<wbr>playground/Admin_Guide.html</a><br>
&gt;&gt; [6] <a href="https://ctomc.github.io/docs-playground/Admin_Guide.pdf" rel="noreferrer" target="_blank">https://ctomc.github.io/docs-<wbr>playground/Admin_Guide.pdf</a><br>
&gt;&gt; [7] <a href="https://github.com/ctomc/docs-playground" rel="noreferrer" target="_blank">https://github.com/ctomc/docs-<wbr>playground</a><br>
&gt;&gt; [8] <a href="https://ctomc.github.io/docs-playground/" rel="noreferrer" target="_blank">https://ctomc.github.io/docs-<wbr>playground/</a><br>
&gt;&gt;<br>
&gt;&gt; ______________________________<wbr>_________________<br>
&gt;&gt; wildfly-dev mailing list<br>
&gt;&gt; <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
&gt;&gt; <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/<wbr>mailman/listinfo/wildfly-dev</a><br>
&gt;<br>
&gt;<br>
&gt;<br>
&gt;<br>
&gt; --<br>
&gt; Brian Stansberry<br>
&gt; Manager, Senior Principal Software Engineer<br>
&gt; Red Hat<br>
&gt;<br>
&gt; ______________________________<wbr>_________________<br>
&gt; wildfly-dev mailing list<br>
&gt; <a href="mailto:wildfly-dev@lists.jboss.org">wildfly-dev@lists.jboss.org</a><br>
&gt; <a href="https://lists.jboss.org/mailman/listinfo/wildfly-dev" rel="noreferrer" target="_blank">https://lists.jboss.org/<wbr>mailman/listinfo/wildfly-dev</a><br>
<br>
<br>
<br>
--<br>
</div></div>- DML<br>
</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>