[wildfly-dev] 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 <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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wildfly-dev/attachments/20171108/7ae52256/attachment.html