One Doc to Rule Them All

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

One Doc to Rule Them All

James Perkins
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
Reply | Threaded
Open this post in threaded view
|

Re: One Doc to Rule Them All

Nicklas Karlsson
I can confirm this exists even outside documentation. One example is http://www.jboss.org/get-involved/ where the reference list says "WildFly 8". Understandable since the interview was made in the age of WF8 but there are plenty of other examples around.

On Fri, May 13, 2016 at 6:32 AM, 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



--
Nicklas Karlsson, +358 40 5062266
Vaakunatie 10 as 7, 20780 Kaarina

_______________________________________________
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

David Lloyd-2
In reply to this post by James Perkins
I like approach 3, assuming that it'll move in to e.g. GitHub.  If
there's an update to a doc, it's a lot easier to backport using git than
Confluence.  Less chance of old docs getting abandoned, and easier for
users to contribute fixes and updates if they can just open a PR for
each affected version.  We're already reasonably well-trained to deal
with old branches.

I don't know how we'd organize it though; I've never done multi-document
things using asciidoc, and also we'd have to publish it somehow
(preferably in an automated manner).

On 05/12/2016 10:32 PM, James Perkins 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
>

--
- DML
_______________________________________________
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 W.Rupp
On 13 May 2016, at 15:12, David M. Lloyd wrote:

> I don't know how we'd organize it though; I've never done multi-document
> things using asciidoc, and also we'd have to publish it somehow
> (preferably in an automated manner).

We have a build pipeline for the hawkular.org website, where the
input is the pages branch of https://github.com/hawkular/hawkular.github.io

If interested talk to Jirka (in cc)
_______________________________________________
wildfly-dev mailing list
[hidden email]
https://lists.jboss.org/mailman/listinfo/wildfly-dev

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

Re: One Doc to Rule Them All

James Perkins
In reply to this post by David Lloyd-2
Yeah I think I prefer approach 3 myself. It just might be a lot of work to get there.

I was thinking we could either use the gh-pages/github.io approach or even just make it part of the wildfly.org [1] repo in a docs subdirectory. I see it being nice in some ways having it on http://wildfly.org.

[1]: https://github.com/wildfly/wildfly.org

On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd <[hidden email]> wrote:
I like approach 3, assuming that it'll move in to e.g. GitHub.  If
there's an update to a doc, it's a lot easier to backport using git than
Confluence.  Less chance of old docs getting abandoned, and easier for
users to contribute fixes and updates if they can just open a PR for
each affected version.  We're already reasonably well-trained to deal
with old branches.

I don't know how we'd organize it though; I've never done multi-document
things using asciidoc, and also we'd have to publish it somehow
(preferably in an automated manner).

On 05/12/2016 10:32 PM, James Perkins 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
>

--
- DML
_______________________________________________
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

James Perkins
In reply to this post by Heiko W.Rupp
Excellent. I'll have a look at how that works. Thanks!

On Fri, May 13, 2016 at 6:54 AM, Heiko W.Rupp <[hidden email]> wrote:
On 13 May 2016, at 15:12, David M. Lloyd wrote:

> I don't know how we'd organize it though; I've never done multi-document
> things using asciidoc, and also we'd have to publish it somehow
> (preferably in an automated manner).

We have a build pipeline for the hawkular.org website, where the
input is the pages branch of https://github.com/hawkular/hawkular.github.io

If interested talk to Jirka (in cc)
_______________________________________________
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

James Perkins
In reply to this post by David Lloyd-2


On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd <[hidden email]> wrote:
I like approach 3, assuming that it'll move in to e.g. GitHub.  If
there's an update to a doc, it's a lot easier to backport using git than
Confluence.  Less chance of old docs getting abandoned, and easier for
users to contribute fixes and updates if they can just open a PR for
each affected version.  We're already reasonably well-trained to deal
with old branches.

I don't know how we'd organize it though; I've never done multi-document
things using asciidoc, and also we'd have to publish it somehow
(preferably in an automated manner).

Actually it does look like there is an include:: option. My guess though is the reason there's a lot of combining asciidoc with awestruct is to build these multi-page sites.

 


--
- DML
_______________________________________________
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

jtgreene
Administrator
In reply to this post by James Perkins
Just as a general note, no matter how we generate our documentation we can always qualify versions. For example we can say "Since version X.y, blah". 

In general software tends to be additive until you hit a major rearchitecture. Currently I think we are forking the documentation too much. 

On May 12, 2016, at 10:33 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

_______________________________________________
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
Also, I think it's far more likely developers will update the current documentation than fix old docs. By having a living doc for all versions you ensure that users always have the most accurate information at their disposal.

On May 13, 2016, at 12:50 PM, Jason T. Greene <[hidden email]> wrote:

Just as a general note, no matter how we generate our documentation we can always qualify versions. For example we can say "Since version X.y, blah". 

In general software tends to be additive until you hit a major rearchitecture. Currently I think we are forking the documentation too much. 

On May 12, 2016, at 10:33 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

_______________________________________________
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
Yes I agree on both counts that we fork too often and we're likely to update new documentation only. This kind of goes with my first option where we keep it more generic e.g. use WildFly rather than WildFly ${version}.

On Fri, May 13, 2016 at 10:53 AM, Jason T. Greene <[hidden email]> wrote:
Also, I think it's far more likely developers will update the current documentation than fix old docs. By having a living doc for all versions you ensure that users always have the most accurate information at their disposal.

On May 13, 2016, at 12:50 PM, Jason T. Greene <[hidden email]> wrote:

Just as a general note, no matter how we generate our documentation we can always qualify versions. For example we can say "Since version X.y, blah". 

In general software tends to be additive until you hit a major rearchitecture. Currently I think we are forking the documentation too much. 

On May 12, 2016, at 10:33 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



--
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

jtgreene
Administrator
Right well basically what I am saying is that instead of forking at a specific point in time, which is really what option 2 is about, we just fork when it really becomes necessary, which is likely a major re-architecture.

While it does sound like I am advocating 1, 3 could meet this as well. We can have one link for “WildFly docs” which is always the most current, and if we were using asciidoc, we could have “archived docs”, which are not maintained but there for reference if need be.


On May 13, 2016, at 12:57 PM, James Perkins <[hidden email]> wrote:

Yes I agree on both counts that we fork too often and we're likely to update new documentation only. This kind of goes with my first option where we keep it more generic e.g. use WildFly rather than WildFly ${version}.

On Fri, May 13, 2016 at 10:53 AM, Jason T. Greene <[hidden email]> wrote:
Also, I think it's far more likely developers will update the current documentation than fix old docs. By having a living doc for all versions you ensure that users always have the most accurate information at their disposal.

On May 13, 2016, at 12:50 PM, Jason T. Greene <[hidden email]> wrote:

Just as a general note, no matter how we generate our documentation we can always qualify versions. For example we can say "Since version X.y, blah". 

In general software tends to be additive until you hit a major rearchitecture. Currently I think we are forking the documentation too much. 

On May 12, 2016, at 10:33 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



--
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

Scott Marlow
In reply to this post by jtgreene


On 05/13/2016 01:50 PM, Jason T. Greene wrote:
> Just as a general note, no matter how we generate our documentation we
> can always qualify versions. For example we can say "Since version X.y,
> blah".

This worked well enough in the old JBoss wiki, except it sometimes got
long (from what I remember).

>
> In general software tends to be additive until you hit a major
> rearchitecture. Currently I think we are forking the documentation too
> much.
>
> On May 12, 2016, at 10:33 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
>
>
> _______________________________________________
> 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 jtgreene
As David stated one thing I do see as a positive for asciidoc is we could do PR's. So if we have some big new feature come in we could also request the submitter to add a docs PR too. That might be asking too much, but it's nice in theory at least :)

On Fri, May 13, 2016 at 11:12 AM, Jason Greene <[hidden email]> wrote:
Right well basically what I am saying is that instead of forking at a specific point in time, which is really what option 2 is about, we just fork when it really becomes necessary, which is likely a major re-architecture.

While it does sound like I am advocating 1, 3 could meet this as well. We can have one link for “WildFly docs” which is always the most current, and if we were using asciidoc, we could have “archived docs”, which are not maintained but there for reference if need be.


On May 13, 2016, at 12:57 PM, James Perkins <[hidden email]> wrote:

Yes I agree on both counts that we fork too often and we're likely to update new documentation only. This kind of goes with my first option where we keep it more generic e.g. use WildFly rather than WildFly ${version}.

On Fri, May 13, 2016 at 10:53 AM, Jason T. Greene <[hidden email]> wrote:
Also, I think it's far more likely developers will update the current documentation than fix old docs. By having a living doc for all versions you ensure that users always have the most accurate information at their disposal.

On May 13, 2016, at 12:50 PM, Jason T. Greene <[hidden email]> wrote:

Just as a general note, no matter how we generate our documentation we can always qualify versions. For example we can say "Since version X.y, blah". 

In general software tends to be additive until you hit a major rearchitecture. Currently I think we are forking the documentation too much. 

On May 12, 2016, at 10:33 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



--
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




--
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

Scott Marlow
IMO, it would probably be nicer if the GIT repo is open.  Requiring a PR
for every doc change, might discourage contributions.

We probably did fork the documentation too often, as contributions
slowed down over time.  If developers are less interested in
contributing documentation, we might want to fork less but also keep it
easy to make changes (e.g. use a wiki/confluence or other online editor).

On 05/13/2016 02:20 PM, James Perkins wrote:

> As David stated one thing I do see as a positive for asciidoc is we
> could do PR's. So if we have some big new feature come in we could also
> request the submitter to add a docs PR too. That might be asking too
> much, but it's nice in theory at least :)
>
> On Fri, May 13, 2016 at 11:12 AM, Jason Greene <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Right well basically what I am saying is that instead of forking at
>     a specific point in time, which is really what option 2 is about, we
>     just fork when it really becomes necessary, which is likely a major
>     re-architecture.
>
>     While it does sound like I am advocating 1, 3 could meet this as
>     well. We can have one link for “WildFly docs” which is always the
>     most current, and if we were using asciidoc, we could have “archived
>     docs”, which are not maintained but there for reference if need be.
>
>
>>     On May 13, 2016, at 12:57 PM, James Perkins <[hidden email]
>>     <mailto:[hidden email]>> wrote:
>>
>>     Yes I agree on both counts that we fork too often and we're likely
>>     to update new documentation only. This kind of goes with my first
>>     option where we keep it more generic e.g. use WildFly rather than
>>     WildFly ${version}.
>>
>>     On Fri, May 13, 2016 at 10:53 AM, Jason T. Greene
>>     <[hidden email] <mailto:[hidden email]>> wrote:
>>
>>         Also, I think it's far more likely developers will update the
>>         current documentation than fix old docs. By having a living
>>         doc for all versions you ensure that users always have the
>>         most accurate information at their disposal.
>>
>>         On May 13, 2016, at 12:50 PM, Jason T. Greene
>>         <[hidden email] <mailto:[hidden email]>> wrote:
>>
>>>         Just as a general note, no matter how we generate our
>>>         documentation we can always qualify versions. For example we
>>>         can say "Since version X.y, blah".
>>>
>>>         In general software tends to be additive until you hit a
>>>         major rearchitecture. Currently I think we are forking the
>>>         documentation too much.
>>>
>>>         On May 12, 2016, at 10:33 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
>>
>>
>>
>>
>>     --
>>     James R. Perkins
>>     JBoss by Red Hat
>>     _______________________________________________
>>     wildfly-dev mailing list
>>     [hidden email] <mailto:[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
>
>
>
>
> --
> 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

David Lloyd-2
One thing you can do on GitHub is, edit a page in-place, and it will
automatically create a PR for you.  This can give the "feel" of a wiki
without sacrificing the control that we need.

On 05/13/2016 01:45 PM, Scott Marlow wrote:

> IMO, it would probably be nicer if the GIT repo is open.  Requiring a PR
> for every doc change, might discourage contributions.
>
> We probably did fork the documentation too often, as contributions
> slowed down over time.  If developers are less interested in
> contributing documentation, we might want to fork less but also keep it
> easy to make changes (e.g. use a wiki/confluence or other online editor).
>
> On 05/13/2016 02:20 PM, James Perkins wrote:
>> As David stated one thing I do see as a positive for asciidoc is we
>> could do PR's. So if we have some big new feature come in we could also
>> request the submitter to add a docs PR too. That might be asking too
>> much, but it's nice in theory at least :)
>>
>> On Fri, May 13, 2016 at 11:12 AM, Jason Greene <[hidden email]
>> <mailto:[hidden email]>> wrote:
>>
>>      Right well basically what I am saying is that instead of forking at
>>      a specific point in time, which is really what option 2 is about, we
>>      just fork when it really becomes necessary, which is likely a major
>>      re-architecture.
>>
>>      While it does sound like I am advocating 1, 3 could meet this as
>>      well. We can have one link for “WildFly docs” which is always the
>>      most current, and if we were using asciidoc, we could have “archived
>>      docs”, which are not maintained but there for reference if need be.
>>
>>
>>>      On May 13, 2016, at 12:57 PM, James Perkins <[hidden email]
>>>      <mailto:[hidden email]>> wrote:
>>>
>>>      Yes I agree on both counts that we fork too often and we're likely
>>>      to update new documentation only. This kind of goes with my first
>>>      option where we keep it more generic e.g. use WildFly rather than
>>>      WildFly ${version}.
>>>
>>>      On Fri, May 13, 2016 at 10:53 AM, Jason T. Greene
>>>      <[hidden email] <mailto:[hidden email]>> wrote:
>>>
>>>          Also, I think it's far more likely developers will update the
>>>          current documentation than fix old docs. By having a living
>>>          doc for all versions you ensure that users always have the
>>>          most accurate information at their disposal.
>>>
>>>          On May 13, 2016, at 12:50 PM, Jason T. Greene
>>>          <[hidden email] <mailto:[hidden email]>> wrote:
>>>
>>>>          Just as a general note, no matter how we generate our
>>>>          documentation we can always qualify versions. For example we
>>>>          can say "Since version X.y, blah".
>>>>
>>>>          In general software tends to be additive until you hit a
>>>>          major rearchitecture. Currently I think we are forking the
>>>>          documentation too much.
>>>>
>>>>          On May 12, 2016, at 10:33 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
>>>
>>>
>>>
>>>
>>>      --
>>>      James R. Perkins
>>>      JBoss by Red Hat
>>>      _______________________________________________
>>>      wildfly-dev mailing list
>>>      [hidden email] <mailto:[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
>>
>>
>>
>>
>> --
>> 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
>

--
- DML
_______________________________________________
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 James Perkins
Has anyone used a good docbook to asciidoc converter, e.g. the docbookrx
discussed at [1] or the O'Reilly thing at [2]?

If we can't have some sort of reasonable conversion it's hard to imagine
us making the move.

[1]
https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/

[2] https://github.com/oreillymedia/docbook2asciidoc

On 5/13/16 10:46 AM, James Perkins wrote:

> Yeah I think I prefer approach 3 myself. It just might be a lot of work
> to get there.
>
> I was thinking we could either use the gh-pages/github.io
> <http://github.io> approach or even just make it part of the wildfly.org
> <http://wildfly.org> [1] repo in a docs subdirectory. I see it being
> nice in some ways having it on http://wildfly.org.
>
> [1]: https://github.com/wildfly/wildfly.org
>
> On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     I like approach 3, assuming that it'll move in to e.g. GitHub.  If
>     there's an update to a doc, it's a lot easier to backport using git than
>     Confluence.  Less chance of old docs getting abandoned, and easier for
>     users to contribute fixes and updates if they can just open a PR for
>     each affected version.  We're already reasonably well-trained to deal
>     with old branches.
>
>     I don't know how we'd organize it though; I've never done multi-document
>     things using asciidoc, and also we'd have to publish it somehow
>     (preferably in an automated manner).
>
>     On 05/12/2016 10:32 PM, James Perkins 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
>     >
>
>     --
>     - DML
>     _______________________________________________
>     wildfly-dev mailing list
>     [hidden email] <mailto:[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
>


--
Brian Stansberry
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

James Perkins
I've looked for a few tools, but hadn't seen this one yet. Looks kind of promising though. If I could figure out how to export the docs to DocBook I'd test it :)

On Fri, May 13, 2016 at 1:26 PM, Brian Stansberry <[hidden email]> wrote:
Has anyone used a good docbook to asciidoc converter, e.g. the docbookrx
discussed at [1] or the O'Reilly thing at [2]?

If we can't have some sort of reasonable conversion it's hard to imagine
us making the move.

[1]
https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/

[2] https://github.com/oreillymedia/docbook2asciidoc

On 5/13/16 10:46 AM, James Perkins wrote:
> Yeah I think I prefer approach 3 myself. It just might be a lot of work
> to get there.
>
> I was thinking we could either use the gh-pages/github.io
> <http://github.io> approach or even just make it part of the wildfly.org
> <http://wildfly.org> [1] repo in a docs subdirectory. I see it being
> nice in some ways having it on http://wildfly.org.
>
> [1]: https://github.com/wildfly/wildfly.org
>
> On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     I like approach 3, assuming that it'll move in to e.g. GitHub.  If
>     there's an update to a doc, it's a lot easier to backport using git than
>     Confluence.  Less chance of old docs getting abandoned, and easier for
>     users to contribute fixes and updates if they can just open a PR for
>     each affected version.  We're already reasonably well-trained to deal
>     with old branches.
>
>     I don't know how we'd organize it though; I've never done multi-document
>     things using asciidoc, and also we'd have to publish it somehow
>     (preferably in an automated manner).
>
>     On 05/12/2016 10:32 PM, James Perkins 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
>     >
>
>     --
>     - DML
>     _______________________________________________
>     wildfly-dev mailing list
>     [hidden email] <mailto:[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
>


--
Brian Stansberry
Senior Principal Software Engineer
JBoss by Red Hat
_______________________________________________
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

Rostislav Svoboda
I like approach used in JBossWS project

Latest documentation on Confluence - https://docs.jboss.org/author/display/JBWS/
Older documentation available on http://docs.jboss.org/jbossws/ - e.g. http://docs.jboss.org/jbossws/5.1.0.Final/ 

Rostislav

----- Original Message -----

> I've looked for a few tools, but hadn't seen this one yet. Looks kind of
> promising though. If I could figure out how to export the docs to DocBook
> I'd test it :)
>
> On Fri, May 13, 2016 at 1:26 PM, Brian Stansberry <
> [hidden email] > wrote:
>
>
> Has anyone used a good docbook to asciidoc converter, e.g. the docbookrx
> discussed at [1] or the O'Reilly thing at [2]?
>
> If we can't have some sort of reasonable conversion it's hard to imagine
> us making the move.
>
> [1]
> https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/
>
> [2] https://github.com/oreillymedia/docbook2asciidoc
>
> On 5/13/16 10:46 AM, James Perkins wrote:
> > Yeah I think I prefer approach 3 myself. It just might be a lot of work
> > to get there.
> >
> > I was thinking we could either use the gh-pages/ github.io
> > < http://github.io > approach or even just make it part of the wildfly.org
> > < http://wildfly.org > [1] repo in a docs subdirectory. I see it being
> > nice in some ways having it on http://wildfly.org .
> >
> > [1]: https://github.com/wildfly/wildfly.org
> >
> > On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd < [hidden email]
> > <mailto: [hidden email] >> wrote:
> >
> > I like approach 3, assuming that it'll move in to e.g. GitHub. If
> > there's an update to a doc, it's a lot easier to backport using git than
> > Confluence. Less chance of old docs getting abandoned, and easier for
> > users to contribute fixes and updates if they can just open a PR for
> > each affected version. We're already reasonably well-trained to deal
> > with old branches.
> >
> > I don't know how we'd organize it though; I've never done multi-document
> > things using asciidoc, and also we'd have to publish it somehow
> > (preferably in an automated manner).
> >
> > On 05/12/2016 10:32 PM, James Perkins 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
> > >
> >
> > --
> > - DML
> > _______________________________________________
> > wildfly-dev mailing list
> > [hidden email] <mailto: [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
> >
>
>
> --
> Brian Stansberry
> Senior Principal Software Engineer
> JBoss by Red Hat
> _______________________________________________
> 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
_______________________________________________
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

Sanne Grinovero

Hi all,
at Hibernate we publish both the blog in.relation.to and the website hibernate.org by pushing  asciidoc changes to github.com.

Documentation of each project is built from asciidoc during the project build, and uploaded as part of each release.

A push - including merging a PR - to website or blog will trigger a CI job which updates the websites. We have a "production" and a "staging" branch.

We also converted all our documentation from docbook, and some of our project still convert the asciidoc documentation into docbook during each release automatically to produce the old style PDF (among other formats).

Documentation is indeed broken up in multiple files, then using includes and variables.. It's particularly nice to inject variable values defined as properties in Maven, we can for example print out versions of dependencies and have them rendered correctly at release time.

The website and the blog use Bob's http://awestruct.org

Have a look at our ci.hibernate.org jobs, or ask us more specific questions we're happy to point to examples of each piece of the puzzle.

It works quite nicely, BUT:
- sometimes I envy your wiki, takes less time to get stuff done. Lower quality though... :P
- rebuilding our blog takes like 15 minutes on good day. That's not great when then you notice yet another typo and have to re-trigger it..
- the gem dependencies for awestruct tend to have weird system dependencies and break often on Fedora... use Docker.

Sanne

On 14 May 2016 10:09, "Rostislav Svoboda" <[hidden email]> wrote:
I like approach used in JBossWS project

Latest documentation on Confluence - https://docs.jboss.org/author/display/JBWS/
Older documentation available on http://docs.jboss.org/jbossws/ - e.g. http://docs.jboss.org/jbossws/5.1.0.Final/

Rostislav

----- Original Message -----
> I've looked for a few tools, but hadn't seen this one yet. Looks kind of
> promising though. If I could figure out how to export the docs to DocBook
> I'd test it :)
>
> On Fri, May 13, 2016 at 1:26 PM, Brian Stansberry <
> [hidden email] > wrote:
>
>
> Has anyone used a good docbook to asciidoc converter, e.g. the docbookrx
> discussed at [1] or the O'Reilly thing at [2]?
>
> If we can't have some sort of reasonable conversion it's hard to imagine
> us making the move.
>
> [1]
> https://blogs.gnome.org/pmkovar/2015/10/27/converting-docbook-into-asciidoc/
>
> [2] https://github.com/oreillymedia/docbook2asciidoc
>
> On 5/13/16 10:46 AM, James Perkins wrote:
> > Yeah I think I prefer approach 3 myself. It just might be a lot of work
> > to get there.
> >
> > I was thinking we could either use the gh-pages/ github.io
> > < http://github.io > approach or even just make it part of the wildfly.org
> > < http://wildfly.org > [1] repo in a docs subdirectory. I see it being
> > nice in some ways having it on http://wildfly.org .
> >
> > [1]: https://github.com/wildfly/wildfly.org
> >
> > On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd < [hidden email]
> > <mailto: [hidden email] >> wrote:
> >
> > I like approach 3, assuming that it'll move in to e.g. GitHub. If
> > there's an update to a doc, it's a lot easier to backport using git than
> > Confluence. Less chance of old docs getting abandoned, and easier for
> > users to contribute fixes and updates if they can just open a PR for
> > each affected version. We're already reasonably well-trained to deal
> > with old branches.
> >
> > I don't know how we'd organize it though; I've never done multi-document
> > things using asciidoc, and also we'd have to publish it somehow
> > (preferably in an automated manner).
> >
> > On 05/12/2016 10:32 PM, James Perkins 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
> > >
> >
> > --
> > - DML
> > _______________________________________________
> > wildfly-dev mailing list
> > [hidden email] <mailto: [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
> >
>
>
> --
> Brian Stansberry
> Senior Principal Software Engineer
> JBoss by Red Hat
> _______________________________________________
> 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
_______________________________________________
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

Brian Stansberry
In reply to this post by James Perkins
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




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