[wildfly-dev] WildFly asciidoc based documentation

Thu Nov 9 11:41:48 EST 2017

See also https://opensource.com/article/17/9/modular-documentation

On Thu, Nov 9, 2017 at 9:50 AM, Tomaž Cerar <tomaz.cerar at gmail.com> wrote:

> https://github.com/redhat-documentation/modular-docs
>
>
>
> --
>
> tomaz
>
>
>
> *From: *Brian Stansberry <brian.stansberry at redhat.com>
> *Sent: *četrtek, 09. november 2017 15:28
> *To: *Tomaž Cerar <tomaz.cerar at gmail.com>
> *Cc: *Bob McWhirter <bmcwhirt at redhat.com>; wildfly-dev at lists.jboss.org
>
> *Subject: *Re: [wildfly-dev] WildFly asciidoc based documentation
>
>
>
>
>
> On Thu, Nov 9, 2017 at 8:19 AM, Tomaž Cerar <tomaz.cerar at gmail.com> 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: *Bob McWhirter <bmcwhirt at redhat.com>
> *Sent: *četrtek, 09. november 2017 01:48
> *To: *Brian Stansberry <brian.stansberry at redhat.com>
> *Cc: *wildfly-dev at lists.jboss.org
> *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 <
> brian.stansberry at redhat.com> 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 <david.lloyd at redhat.com>
> 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
> <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
>
>
>
>
>
> --
>
> 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
>
>
>
>
>
>
>
> --
>
> Brian Stansberry
>
> Manager, Senior Principal Software Engineer
>
> Red Hat
>
>
>

-- 
Brian Stansberry
Manager, Senior Principal Software Engineer
Red Hat
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wildfly-dev/attachments/20171109/2e19d7ae/attachment-0001.html 