[wildfly-dev] WildFly asciidoc based documentation

[Rostislav Svoboda]

Hi Tomaz.

How would this change translate to product branch ?

Would it also make sense to extract parts of documentation related to "Servlet-Only Distribution" provided on http://wildfly.org/downloads/ ?
I think current documentation presumes full app server distribution.

Maybe going further it would also make sense to compose docs via provisioning tool (https://github.com/aloubyansky/pm/) so users could have up to date documentation related to stuff they are using in their setup ... e.g. when they compose server just with undertow + resteasy + hibernate they wouldn't get documentation for clustering, soap webservices, messaging, ...
The same could also happen for Quickstarts, have them provisioned via pm (or similar) tool based on the selected components/feature packs.

Rostislav

----- Original Message -----
> 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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev