[wildfly-dev] WildFly asciidoc based documentation

[Bill Burke]

Take a look at Keycloak docs:

https://github.com/keycloak/keycloak-documentation

All asciidoc.  They require a build a build that tests automatically
tests links and any other thing that can be automatically tested.  Our
product docs also derive directly from community docs which makes
things a lot less work for everybody.  Both community and product
benefit.


On Wed, Sep 20, 2017 at 7:00 AM, Rostislav Svoboda <rsvoboda at redhat.com> wrote:
> 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
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



-- 
Bill Burke
Red Hat