WildFly asciidoc based documentation

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

WildFly asciidoc based documentation

Tomaž Cerar-2
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


_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: 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
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--
Bill Burke
Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

Brian Stansberry
In reply to this post by Tomaž Cerar-2
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 <[hidden email]> 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


_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev



--
Brian Stansberry
Manager, Senior Principal Software Engineer
Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

David Lloyd-2
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
<[hidden email]> 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--
- DML

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

Brian Stansberry
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.

On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <[hidden email]> wrote:
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
<[hidden email]> 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--
- DML



--
Brian Stansberry
Manager, Senior Principal Software Engineer
Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

Bob McWhirter
We have recent used he doc teams “modular documentation templates” and I think they are lovely and also makes the docs team happy. 

Ask your doctor if modular documentation templates are right for you. 

Bob

On Wed, Nov 8, 2017 at 12:40 PM Brian Stansberry <[hidden email]> wrote:
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.

On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <[hidden email]> wrote:
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
<[hidden email]> 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--
- DML



--
Brian Stansberry
Manager, Senior Principal Software Engineer
Red Hat
_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

Tomaž Cerar-2

I've updated PR https://github.com/wildfly/wildfly/pull/10523

That brings in converted confluence documentation.

It is synced with todays content in confluence.

 

This is just a start, going forward we should

 

  • Split docs between core & full
  • Each subsystem could have docs folder that would be than agreggated
  • Publish docs somewhere. Maybe use GH for start http://wildfly.github.io/
  • Restrucutre docs into few books instead of what we have now.

 

--

tomaz

 

 

From: [hidden email]
Sent: četrtek, 09. november 2017 01:48
To: [hidden email]
Cc: [hidden email]
Subject: Re: [wildfly-dev] WildFly asciidoc based documentation

 

We have recent used he doc teams “modular documentation templates” and I think they are lovely and also makes the docs team happy. 

 

Ask your doctor if modular documentation templates are right for you. 

 

Bob

 

On Wed, Nov 8, 2017 at 12:40 PM Brian Stansberry <[hidden email]> wrote:

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.

 

On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <[hidden email]> wrote:

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
<[hidden email]> 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--

- DML



 

--

Brian Stansberry

Manager, Senior Principal Software Engineer

Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

 


_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

Brian Stansberry

On Thu, Nov 9, 2017 at 8:19 AM, Tomaž Cerar <[hidden email]> wrote:

I've updated PR https://github.com/wildfly/wildfly/pull/10523

That brings in converted confluence documentation.

It is synced with todays content in confluence.

 

This is just a start, going forward we should

 

  • Split docs between core & full
  • Each subsystem could have docs folder that would be than agreggated
  • Publish docs somewhere. Maybe use GH for start http://wildfly.github.io/
  • Restrucutre docs into few books instead of what we have now.
As we get into this last bit, we should look into the modular stuff Bob mentioned. It sounds like it would mean a large scale rewrite, so if we start doing things that are more than just moving some files around we should consider the bigger picture.

 

--

tomaz

 

 

From: [hidden email]
Sent: četrtek, 09. november 2017 01:48
To: [hidden email]
Cc: [hidden email]
Subject: Re: [wildfly-dev] WildFly asciidoc based documentation

 

We have recent used he doc teams “modular documentation templates” and I think they are lovely and also makes the docs team happy. 

 

Ask your doctor if modular documentation templates are right for you. 

 

Bob

 

On Wed, Nov 8, 2017 at 12:40 PM Brian Stansberry <[hidden email]> wrote:

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.

 

On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <[hidden email]> wrote:

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
<[hidden email]> 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--

- DML



 

--

Brian Stansberry

Manager, Senior Principal Software Engineer

Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

 




--
Brian Stansberry
Manager, Senior Principal Software Engineer
Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

Tomaž Cerar-2

https://github.com/redhat-documentation/modular-docs

 

--

tomaz

 

From: [hidden email]
Sent: četrtek, 09. november 2017 15:28
To: [hidden email]
Cc: [hidden email]; [hidden email]
Subject: Re: [wildfly-dev] WildFly asciidoc based documentation

 

 

On Thu, Nov 9, 2017 at 8:19 AM, Tomaž Cerar <[hidden email]> wrote:

I've updated PR https://github.com/wildfly/wildfly/pull/10523

That brings in converted confluence documentation.

It is synced with todays content in confluence.

 

This is just a start, going forward we should

 

  • Split docs between core & full
  • Each subsystem could have docs folder that would be than agreggated
  • Publish docs somewhere. Maybe use GH for start http://wildfly.github.io/
  • Restrucutre docs into few books instead of what we have now.

As we get into this last bit, we should look into the modular stuff Bob mentioned. It sounds like it would mean a large scale rewrite, so if we start doing things that are more than just moving some files around we should consider the bigger picture.

 

 

--

tomaz

 

 

From: [hidden email]
Sent: četrtek, 09. november 2017 01:48
To: [hidden email]
Cc: [hidden email]
Subject: Re: [wildfly-dev] WildFly asciidoc based documentation

 

We have recent used he doc teams “modular documentation templates” and I think they are lovely and also makes the docs team happy. 

 

Ask your doctor if modular documentation templates are right for you. 

 

Bob

 

On Wed, Nov 8, 2017 at 12:40 PM Brian Stansberry <[hidden email]> wrote:

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.

 

On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <[hidden email]> wrote:

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
<[hidden email]> 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--

- DML



 

--

Brian Stansberry

Manager, Senior Principal Software Engineer

Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

 



 

--

Brian Stansberry

Manager, Senior Principal Software Engineer

Red Hat

 


_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev
Reply | Threaded
Open this post in threaded view
|

Re: WildFly asciidoc based documentation

Brian Stansberry

On Thu, Nov 9, 2017 at 9:50 AM, Tomaž Cerar <[hidden email]> wrote:

https://github.com/redhat-documentation/modular-docs

 

--

tomaz

 

From: [hidden email]
Sent: četrtek, 09. november 2017 15:28
To: [hidden email]
Cc: [hidden email]; [hidden email]


Subject: Re: [wildfly-dev] WildFly asciidoc based documentation

 

 

On Thu, Nov 9, 2017 at 8:19 AM, Tomaž Cerar <[hidden email]> wrote:

I've updated PR https://github.com/wildfly/wildfly/pull/10523

That brings in converted confluence documentation.

It is synced with todays content in confluence.

 

This is just a start, going forward we should

 

  • Split docs between core & full
  • Each subsystem could have docs folder that would be than agreggated
  • Publish docs somewhere. Maybe use GH for start http://wildfly.github.io/
  • Restrucutre docs into few books instead of what we have now.

As we get into this last bit, we should look into the modular stuff Bob mentioned. It sounds like it would mean a large scale rewrite, so if we start doing things that are more than just moving some files around we should consider the bigger picture.

 

 

--

tomaz

 

 

From: [hidden email]
Sent: četrtek, 09. november 2017 01:48
To: [hidden email]
Cc: [hidden email]
Subject: Re: [wildfly-dev] WildFly asciidoc based documentation

 

We have recent used he doc teams “modular documentation templates” and I think they are lovely and also makes the docs team happy. 

 

Ask your doctor if modular documentation templates are right for you. 

 

Bob

 

On Wed, Nov 8, 2017 at 12:40 PM Brian Stansberry <[hidden email]> wrote:

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.

 

On Wed, Nov 8, 2017 at 7:04 AM, David Lloyd <[hidden email]> wrote:

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
<[hidden email]> 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 <[hidden email]> 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
>> [hidden email]
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> [hidden email]
> https://lists.jboss.org/mailman/listinfo/wildfly-dev



--

- DML



 

--

Brian Stansberry

Manager, Senior Principal Software Engineer

Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

 



 

--

Brian Stansberry

Manager, Senior Principal Software Engineer

Red Hat

 




--
Brian Stansberry
Manager, Senior Principal Software Engineer
Red Hat

_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev