[wildfly-dev] WildFly asciidoc based documentation

[David Lloyd]

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



-- 
- DML