One Doc to Rule Them All

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

Re: One Doc to Rule Them All

James Perkins
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.



On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <[hidden email]> 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 <[hidden email]> 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
[hidden email]
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

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

Re: 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.


On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <[hidden email]> 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.



On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <[hidden email]> 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 <[hidden email]> 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
[hidden email]
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

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

Re: One Doc to Rule Them All

Emmanuel Hugonnet
Hi,
Should we have a maintenance branch for the current stable version documentation (maybe on gitbook) and a living documentation (using github
rendering) or just the living doc ?


On 25/07/2016 19:40, James Perkins wrote:

> 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 <[hidden email] <mailto:[hidden email]>> 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 <[hidden email] <mailto:[hidden email]>> 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 <[hidden email] <mailto:[hidden email]>> 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
>>         [hidden email] <mailto:[hidden email]>
>>         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
>
>
> _______________________________________________
> 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

signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: One Doc to Rule Them All

Bob McWhirter
In reply to this post by James Perkins
I’ve been quite pleased with GitBook.

I’ve not worked with git branches with it, but it does work with commits (and occasionally with tags, but sometimes I’ve failed to make them work).

Basically, every commit produces a new published site, and you can ref any sha1 (or tag, sometimes).

So we keep the repository HEAD as “living” on-going document.

At each release, we tag and then reference that SHA1 for that release’s version of the docs.

See


We use AsciiDoc but you can use Markdown also and make that choice on a per-chapter basis.

Additionally, there is a 100% local toolchain, so you can work locally with your favorite editor and see the build in real-time.

Plus, there’s a “native” editor, which is basically a local version of the online editor, based upon Chrome.  I don’t love it, especially since they took away my vi keybindings.

It also supports plugins, which we haven’t really explored yet, but they’re just node.js packages from npm.

I also talked Stian/Bill into GitBook for Keycloak.

Another benefit: it doesn’t take 45 seconds to load a page you find via Google because it’s based on a jboss.org-hosted Confluence.

-Bob


On Mon, Jul 25, 2016 at 1:40 PM, James Perkins <[hidden email]> wrote:
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.


On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <[hidden email]> 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.



On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <[hidden email]> 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 <[hidden email]> 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
[hidden email]
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

_______________________________________________
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: One Doc to Rule Them All

James Perkins
In reply to this post by Emmanuel Hugonnet


On Mon, Jul 25, 2016 at 10:57 AM, Emmanuel Hugonnet <[hidden email]> wrote:
Hi,
Should we have a maintenance branch for the current stable version documentation (maybe on gitbook) and a living documentation (using github
rendering) or just the living doc ?



I think it kind of depends on the framework we choose. If we stick with Confluence I think we could just have a WFLY document id and then once we release we make a copy of that version. The downside is if you do find a mistake you might have to change it in a few different spots.

Regardless of the framework it could be a bit tricky for micro-releases if master has already changed when making a snapshot.
 

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



--
James R. Perkins
JBoss by 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: One Doc to Rule Them All

Brian Stansberry
In reply to this post by Bob McWhirter
Who is hosting the gitbook stuff?

Lazy question I suspect, but I promise I poked around a bit first and it wasn’t completely obvious. :)

On Jul 25, 2016, at 1:46 PM, Bob McWhirter <[hidden email]> wrote:

I’ve been quite pleased with GitBook.

I’ve not worked with git branches with it, but it does work with commits (and occasionally with tags, but sometimes I’ve failed to make them work).

Basically, every commit produces a new published site, and you can ref any sha1 (or tag, sometimes).

So we keep the repository HEAD as “living” on-going document.

At each release, we tag and then reference that SHA1 for that release’s version of the docs.

See


We use AsciiDoc but you can use Markdown also and make that choice on a per-chapter basis.

Additionally, there is a 100% local toolchain, so you can work locally with your favorite editor and see the build in real-time.

Plus, there’s a “native” editor, which is basically a local version of the online editor, based upon Chrome.  I don’t love it, especially since they took away my vi keybindings.

It also supports plugins, which we haven’t really explored yet, but they’re just node.js packages from npm.

I also talked Stian/Bill into GitBook for Keycloak.

Another benefit: it doesn’t take 45 seconds to load a page you find via Google because it’s based on a jboss.org-hosted Confluence.

-Bob


On Mon, Jul 25, 2016 at 1:40 PM, James Perkins <[hidden email]> wrote:
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.


On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <[hidden email]> 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.



On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <[hidden email]> 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 <[hidden email]> 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
[hidden email]
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

_______________________________________________
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

-- 
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by 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: One Doc to Rule Them All

Tomaž Cerar-2

On Mon, Jul 25, 2016 at 10:52 PM, Brian Stansberry <[hidden email]> wrote:
Who is hosting the gitbook stuff?


whois and friends say it is ec2

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

Re: One Doc to Rule Them All

Brian Stansberry
Thanks. That’s an implementation choice of whoever is providing this service though.

It seems it’s a company named Friend Code, Inc.

On Jul 25, 2016, at 4:32 PM, Tomaž Cerar <[hidden email]> wrote:


On Mon, Jul 25, 2016 at 10:52 PM, Brian Stansberry <[hidden email]> wrote:
Who is hosting the gitbook stuff?


whois and friends say it is ec2

-- 
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by 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: One Doc to Rule Them All

Heiko Braun
Don't know the company behind gitbook, or how they host their site. But you can also take the gitbooks npm and run it on your own. It's also a nice way to edit/view docs locally. But for the majority of cases you can simply edit the file right on github, which is really convinient. 

I've spend quiet some time with this for swarm, so if you need any help with this contact me offline.

Regards, Heiko

Am 25.07.2016 um 23:56 n Brian Stansberry <[hidden email]>:

Thanks. That’s an implementation choice of whoever is providing this service though.

It seems it’s a company named Friend Code, Inc.

On Jul 25, 2016, at 4:32 PM, Tomaž Cerar <[hidden email]> wrote:


On Mon, Jul 25, 2016 at 10:52 PM, Brian Stansberry <[hidden email]> wrote:
Who is hosting the gitbook stuff?


whois and friends say it is ec2

-- 
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by 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: One Doc to Rule Them All

Richard Opalka
In reply to this post by James Perkins

Just FYI there's documentation framework decision going on on Linux Kernel these days:

http://lwn.net/Articles/692704/

There are pros and cons being evaluated of different doc. generation frameworks.

Rio


On 07/25/2016 08:46 PM, James Perkins wrote:


On Mon, Jul 25, 2016 at 10:57 AM, Emmanuel Hugonnet <[hidden email]> wrote:
Hi,
Should we have a maintenance branch for the current stable version documentation (maybe on gitbook) and a living documentation (using github
rendering) or just the living doc ?



I think it kind of depends on the framework we choose. If we stick with Confluence I think we could just have a WFLY document id and then once we release we make a copy of that version. The downside is if you do find a mistake you might have to change it in a few different spots.

Regardless of the framework it could be a bit tricky for micro-releases if master has already changed when making a snapshot.
 

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



--
James R. Perkins
JBoss by Red Hat


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

-- 
Richard Opalka
Principal Software Engineer
Red Hat JBoss Middleware
Mobile: +420 731 186 942
E-mail: [hidden email]

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

Re: One Doc to Rule Them All

Carl Harris
In reply to this post by James Perkins

On Jul 25, 2016, at 1:40 PM, James Perkins <[hidden email]> wrote:
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.

This has probably already been mentioned somewhere in this thread, but a related advantage to an asciidoc (or similar) approach using git, is that you can more easily take documentation contributions in the form of pull requests. I often find myself wanting to suggest a revision, especially after figuring out how to do something that wasn't clearly explained, but apart from adding comments to the page (which are difficult to put in context), there is no good way to suggest revisions in Confluence.

carl

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

Re: One Doc to Rule Them All

James Perkins


On Fri, Jul 29, 2016 at 6:42 AM, Carl Harris <[hidden email]> wrote:

On Jul 25, 2016, at 1:40 PM, James Perkins <[hidden email]> wrote:
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.

This has probably already been mentioned somewhere in this thread, but a related advantage to an asciidoc (or similar) approach using git, is that you can more easily take documentation contributions in the form of pull requests. I often find myself wanting to suggest a revision, especially after figuring out how to do something that wasn't clearly explained, but apart from adding comments to the page (which are difficult to put in context), there is no good way to suggest revisions in Confluence.


This is something I didn't consider. Thank you for pointing it out.

Out of curiosity is there a reason you don't want to just update the document itself?
 
carl

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



--
James R. Perkins
JBoss by 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: One Doc to Rule Them All

Carl Harris

On Jul 29, 2016, at 1:16 PM, James Perkins <[hidden email]> wrote:

On Fri, Jul 29, 2016 at 6:42 AM, Carl Harris <[hidden email]> wrote:
This has probably already been mentioned somewhere in this thread, but a related advantage to an asciidoc (or similar) approach using git, is that you can more easily take documentation contributions in the form of pull requests.
This is something I didn't consider. Thank you for pointing it out. Out of curiosity is there a reason you don't want to just update the document itself?

Apart from the issue of needing permission to do so, as I contributor I would feel more confident about suggesting a revision through a pull request, as opposed to committing a revision. Someone more familiar with the documentation would be able to ensure that conventions are appropriately followed, that the revision doesn't change the semantics in a way that is incorrect or inappropriate, etc. Basically, all the same benefits of any code review, but applied to documentation.

Having used a couple of open source products with freely editable documentation wikis, I'd say that even a minimal process of reviewing and merging changes is more likely to result in a consistent and useful document than simply allowing community edits. Again, just my 2 cents.

carl




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

Re: One Doc to Rule Them All

jtgreene
Administrator
In reply to this post by James Perkins
I think we should stick with what we have, which works well enough, and just have a live / always up to date doc.

Everyone is pretty busy at the moment, so to switch to any new option, the starting point would be a volunteer willing to own all of the porting and reformatting work on all of our existing content. 


On May 12, 2016, at 10:32 PM, James Perkins <[hidden email]> 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
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

--
Jason T. Greene
WildFly Lead / JBoss EAP Platform Architect
JBoss, a division of 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: One Doc to Rule Them All

Brian Stansberry
Practical tip:

tl;dr;

Don’t include the Confluence space prefix in the markup for cross document links.

Long version:

An issue with using a "live / always up to date doc” is I expect we’ll want to snapshot it when we do releases, at least for majors. The way confluence creates links between pages can work against that though.

But this can be mitigated with careful work.

Say I want to create a link in the “Admin Guide” page to the “RBAC” page. The little “link” icon at the top left of the editor helps me do that. The problem is it creates markup like this:

[WFLY:RBAC]

That link will be a problem when we create a snapshot of the docs for WildFly 11 since in the snapshot it will still say “WFLY” and the effective URL wll be 


and not the WFLY11 snapshot URL:


Anyone following the link will get directed to the then current docs, which may have inaccurate information for WildFly 11. (Right now our docs have the opposite problem that James mentioned on this thread; the WFLY10 docs are a copy of WFLY9 which was a copy of WFLY8 and when those copies were created a bunch of links pointing to [WFLY9:xxx} or even earlier were created.)

Avoiding this problem just takes a bit of care though. If you use the link button, edit the resulting link test to remove the “WFLY:" space prefix, resulting in

[RBAC]

With that syntax the link becomes relative to the current document’s space, and when that space is copied the copies will also have relative links.

On Jul 29, 2016, at 2:54 PM, Jason Greene <[hidden email]> wrote:

I think we should stick with what we have, which works well enough, and just have a live / always up to date doc.

Everyone is pretty busy at the moment, so to switch to any new option, the starting point would be a volunteer willing to own all of the porting and reformatting work on all of our existing content. 


On May 12, 2016, at 10:32 PM, James Perkins <[hidden email]> 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
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

--
Jason T. Greene
WildFly Lead / JBoss EAP Platform Architect
JBoss, a division of Red Hat

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

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




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