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