<div dir="ltr">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.</div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Nov 8, 2017 at 7:04 AM, David 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: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>
<<a href="mailto:brian.stansberry@redhat.com">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">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" rel="noreferrer" 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" rel="noreferrer" 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" rel="noreferrer" 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" rel="noreferrer" target="_blank">https://github.com/wildfly/<wbr>wildfly/pull/10523</a><br>
>> [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>
>> [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>
>> [7] <a href="https://github.com/ctomc/docs-playground" rel="noreferrer" target="_blank">https://github.com/ctomc/docs-<wbr>playground</a><br>
>> [8] <a href="https://ctomc.github.io/docs-playground/" rel="noreferrer" 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">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/<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">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/<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>