Re: [wildfly-dev] WildFly asciidoc based documentation

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