[wildfly-dev] One Doc to Rule Them All

[James Perkins]

Just one more follow as Tomaz mentioned to me, another option would be
https://www.gitbook.com/. Both WildFly Swarm [1] and JBeret [2] use it.

[1]: https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/
[2]: https://jberet.gitbooks.io/jberet-user-guide/content/

On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <jperkins at redhat.com> wrote:

> Thanks for bringing this back up Brian. I was just about to do the same :)
>
> The only idea I'm personally opposed to is the "fork for every release"
> Though thinking of it as a live doc where we snapshot it for a release is
> not a bad idea. We could just have a WFLY project that we snapshot for
> every release. We just need to be careful about using versioning when
> writing the docs, unless it's a "Since WIldFly whatever" type of thing. We
> just want to avoid the "In WildFly x".
>
> With regards to the linking problem, I'm not sure if we (myself included)
> are just linking incorrectly between documents or it's just a limitation of
> Confluence. It looks like most links are done like [WFLY8:Implicit module
> dependencies for deployments]. I noticed some don't have the
> "WFLY${version}" prefix so maybe that's the way to go. When you use the
> linking function in confluence it adds the doc reference to the link which
> could be part of the problem.
>
> There are also docs that just point to old information. Like the main page
> references Java EE 6 getting started [1]. The  Some pages are just dead too
> [2]. In some places, I tried to fix the ones I found in the WFLY10 docs, it
> just references the wrong version of WildFly. A lot of XML references too
> which likely point to older namespaces, maybe not a huge deal though.
>
> Overall they're not bad. They just need a little TLC. I do think too there
> is probably some bigger chunks we can get rid of like a lot of the
> quickstart section since we have it all on GitHub. Also subsystem
> references could be replaced with WildScribe.
>
> Anyway, I'm up for anything that allows the documentation to be
> consistent, easy to write and easy to use. The main attraction for me to
> asciidoc is being able to use git for versioning as well as being able to
> use variables. I don't however know how well asciidoc deals with multiple
> documents and combining them together.
>
> Regardless of the direction I'm willing to put some time into
> fixing/updating it. I just think before we invest any time we make a firm
> decision on the direction we want to go.
>
>
> [1]:
> https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-DeveloperGuides
> [2]:
> https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+Recommended+Practices
>
> On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <
> brian.stansberry at redhat.com> wrote:
>
>> So what are we going to do about this?
>>
>> We’ve now reached the point where we need to start generating
>> documentation for WildFly 11. And we’re beginning to require devs, at least
>> those working for Red Hat, to write some sort of community doc as part of
>> getting RFEs resolved. So docs infrastructure issue are beginning to impact
>> our ability to get code changes in.
>>
>> My 2 cents: an asciidoctor and git based approach sounds good, but unless
>> we have resources available to make it happen quickly basically starting
>> from today, we need to devise a strategy based on continuing to use
>> confluence.
>>
>> The biggest problem I saw in James’ original post was "Links take you to
>> old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.” If
>> that’s an inherent problem in cloning docs it’s hard to deal with. Having a
>> living document isn’t so hard; you just write as if it’s a living doc and
>> say things like “Since WildFly 10” etc. But if you can’t snapshot the
>> living doc for a release without creating a lot of bad links, that’s a
>> problem.
>>
>> On May 12, 2016, at 10:32 PM, James Perkins <jperkins at redhat.com> wrote:
>>
>> I've been reading the WildFly documentation [1] quite a bit lately and
>> noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly
>> 10 (or 9) documentation. Sometimes it references JBoss AS 7. Links take you
>> to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.
>> Sometimes documentation is just plain out of date referencing behavior that
>> has possibly been removed or replaced by something better.
>>
>> This has happened because we keep copying the documentation over each
>> time we have a new version. Overall this makes sense as a lot of it doesn't
>> need to be changed. However it leaves reading the documentation confusing.
>> Reading documentation for WildFly 10 and seeing WildFly 8 in the text with
>> a link for AS72 isn't very user friendly as I'm sure we can all agree.
>>
>> There's a few different ways we could go with this.
>>
>> Approach 1:
>> One, probably the easiest, is to use a single confluence project. We'd
>> need to remove the version numbers from the text, which I think we should
>> do anyway. Instead of referencing WildFly 10 we just reference it as
>> WildFly.
>>
>> An issue I can think of with this approach is some how annotating or
>> referencing that parts of the documentation only work with ${version}. For
>> example new features would have to be noted they only work with ${version}+.
>>
>>
>> Approach 2:
>> Essentially he same as approach 1 only do allow different Confluence
>> projects for the different Java EE target version. So WIldFly 8, 9 and 10
>> would all be documented under something like WFLYEE7.
>>
>> Approach 3
>> Switch to using something like asciidoc which can use variables and
>> generate links to the correct content. While this approach is probably
>> takes the most work up front, it seems like like it would be easier to
>> maintain between releases.
>>
>> Any other suggestions are welcome.
>>
>> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>>
>> --
>> James R. Perkins
>> JBoss by 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
>> JBoss by Red Hat
>>
>>
>>
>>
>
>
> --
> James R. Perkins
> JBoss by Red Hat
>



-- 
James R. Perkins
JBoss by Red Hat
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wildfly-dev/attachments/20160725/3c831d03/attachment.html