5:32 a.m.
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
6:26 a.m.
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 <jperkins(a)redhat.com> wrote:
I've been reading the WildFly documentation [1] quite a bit
lately and
noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly
10 (or 9) documentation. Sometimes it references JBoss AS 7. Links take you
to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.
Sometimes documentation is just plain out of date referencing behavior that
has possibly been removed or replaced by something better.
This has happened because we keep copying the documentation over each time
we have a new version. Overall this makes sense as a lot of it doesn't need
to be changed. However it leaves reading the documentation confusing.
Reading documentation for WildFly 10 and seeing WildFly 8 in the text with
a link for AS72 isn't very user friendly as I'm sure we can all agree.
There's a few different ways we could go with this.
Approach 1:
One, probably the easiest, is to use a single confluence project. We'd
need to remove the version numbers from the text, which I think we should
do anyway. Instead of referencing WildFly 10 we just reference it as
WildFly.
An issue I can think of with this approach is some how annotating or
referencing that parts of the documentation only work with ${version}. For
example new features would have to be noted they only work with ${version}+.
Approach 2:
Essentially he same as approach 1 only do allow different Confluence
projects for the different Java EE target version. So WIldFly 8, 9 and 10
would all be documented under something like WFLYEE7.
Approach 3
Switch to using something like asciidoc which can use variables and
generate links to the correct content. While this approach is probably
takes the most work up front, it seems like like it would be easier to
maintain between releases.
Any other suggestions are welcome.
[1]: https://docs.jboss.org/author/display/WFLY10/Documentation
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Nicklas Karlsson, +358 40 5062266
Vaakunatie 10 as 7, 20780 Kaarina
3:12 p.m.
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
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
- DML
3:54 p.m.
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)
5:46 p.m.
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 <david.lloyd(a)redhat.com>
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
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
--
- DML
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
5:56 p.m.
Excellent. I'll have a look at how that works. Thanks!
On Fri, May 13, 2016 at 6:54 AM, Heiko W.Rupp <hrupp(a)redhat.com> 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
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
6 p.m.
On Fri, May 13, 2016 at 6:12 AM, David M. Lloyd <david.lloyd(a)redhat.com>
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.
[1]: http://www.methods.co.nz/asciidoc/userguide.html#X63
--
- DML
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
7:50 p.m.
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
<jperkins(a)redhat.com> wrote:
I've been reading the WildFly documentation [1] quite a bit lately and noticing a lot
of issues. Sometimes it references WildFly 8 in the WildFly 10 (or 9) documentation.
Sometimes it references JBoss AS 7. Links take you to old documentation, e.g. a WFLY10 doc
takes you to a page for WFLY8. Sometimes documentation is just plain out of date
referencing behavior that has possibly been removed or replaced by something better.
This has happened because we keep copying the documentation over each time we have a new
version. Overall this makes sense as a lot of it doesn't need to be changed. However
it leaves reading the documentation confusing. Reading documentation for WildFly 10 and
seeing WildFly 8 in the text with a link for AS72 isn't very user friendly as I'm
sure we can all agree.
There's a few different ways we could go with this.
Approach 1:
One, probably the easiest, is to use a single confluence project. We'd need to remove
the version numbers from the text, which I think we should do anyway. Instead of
referencing WildFly 10 we just reference it as WildFly.
An issue I can think of with this approach is some how annotating or referencing that
parts of the documentation only work with ${version}. For example new features would have
to be noted they only work with ${version}+.
Approach 2:
Essentially he same as approach 1 only do allow different Confluence projects for the
different Java EE target version. So WIldFly 8, 9 and 10 would all be documented under
something like WFLYEE7.
Approach 3
Switch to using something like asciidoc which can use variables and generate links to the
correct content. While this approach is probably takes the most work up front, it seems
like like it would be easier to maintain between releases.
Any other suggestions are welcome.
[1]: https://docs.jboss.org/author/display/WFLY10/Documentation
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
7:53 p.m.
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
<jason.greene(a)redhat.com> 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 <jperkins(a)redhat.com> wrote:
>
> I've been reading the WildFly documentation [1] quite a bit lately and noticing a
lot of issues. Sometimes it references WildFly 8 in the WildFly 10 (or 9) documentation.
Sometimes it references JBoss AS 7. Links take you to old documentation, e.g. a WFLY10 doc
takes you to a page for WFLY8. Sometimes documentation is just plain out of date
referencing behavior that has possibly been removed or replaced by something better.
>
> This has happened because we keep copying the documentation over each time we have a
new version. Overall this makes sense as a lot of it doesn't need to be changed.
However it leaves reading the documentation confusing. Reading documentation for WildFly
10 and seeing WildFly 8 in the text with a link for AS72 isn't very user friendly as
I'm sure we can all agree.
>
> There's a few different ways we could go with this.
>
> Approach 1:
> One, probably the easiest, is to use a single confluence project. We'd need to
remove the version numbers from the text, which I think we should do anyway. Instead of
referencing WildFly 10 we just reference it as WildFly.
>
> An issue I can think of with this approach is some how annotating or referencing that
parts of the documentation only work with ${version}. For example new features would have
to be noted they only work with ${version}+.
>
>
> Approach 2:
> Essentially he same as approach 1 only do allow different Confluence projects for the
different Java EE target version. So WIldFly 8, 9 and 10 would all be documented under
something like WFLYEE7.
>
> Approach 3
> Switch to using something like asciidoc which can use variables and generate links to
the correct content. While this approach is probably takes the most work up front, it
seems like like it would be easier to maintain between releases.
>
> Any other suggestions are welcome.
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>
> --
> James R. Perkins
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
7:57 p.m.
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 <jason.greene(a)redhat.com>
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 <jason.greene(a)redhat.com>
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 <jperkins(a)redhat.com> wrote:
I've been reading the WildFly documentation [1] quite a bit lately and
noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly
10 (or 9) documentation. Sometimes it references JBoss AS 7. Links take you
to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.
Sometimes documentation is just plain out of date referencing behavior that
has possibly been removed or replaced by something better.
This has happened because we keep copying the documentation over each time
we have a new version. Overall this makes sense as a lot of it doesn't need
to be changed. However it leaves reading the documentation confusing.
Reading documentation for WildFly 10 and seeing WildFly 8 in the text with
a link for AS72 isn't very user friendly as I'm sure we can all agree.
There's a few different ways we could go with this.
Approach 1:
One, probably the easiest, is to use a single confluence project. We'd
need to remove the version numbers from the text, which I think we should
do anyway. Instead of referencing WildFly 10 we just reference it as
WildFly.
An issue I can think of with this approach is some how annotating or
referencing that parts of the documentation only work with ${version}. For
example new features would have to be noted they only work with ${version}+.
Approach 2:
Essentially he same as approach 1 only do allow different Confluence
projects for the different Java EE target version. So WIldFly 8, 9 and 10
would all be documented under something like WFLYEE7.
Approach 3
Switch to using something like asciidoc which can use variables and
generate links to the correct content. While this approach is probably
takes the most work up front, it seems like like it would be easier to
maintain between releases.
Any other suggestions are welcome.
[1]: https://docs.jboss.org/author/display/WFLY10/Documentation
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
8:12 p.m.
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
<jperkins(a)redhat.com> 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 <jason.greene(a)redhat.com
<mailto:jason.greene@redhat.com>> 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 <jason.greene(a)redhat.com
<mailto:jason.greene@redhat.com>> 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 <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
>
>> I've been reading the WildFly documentation [1] quite a bit lately and
noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly 10 (or 9)
documentation. Sometimes it references JBoss AS 7. Links take you to old documentation,
e.g. a WFLY10 doc takes you to a page for WFLY8. Sometimes documentation is just plain out
of date referencing behavior that has possibly been removed or replaced by something
better.
>>
>> This has happened because we keep copying the documentation over each time we
have a new version. Overall this makes sense as a lot of it doesn't need to be
changed. However it leaves reading the documentation confusing. Reading documentation for
WildFly 10 and seeing WildFly 8 in the text with a link for AS72 isn't very user
friendly as I'm sure we can all agree.
>>
>> There's a few different ways we could go with this.
>>
>> Approach 1:
>> One, probably the easiest, is to use a single confluence project. We'd need
to remove the version numbers from the text, which I think we should do anyway. Instead of
referencing WildFly 10 we just reference it as WildFly.
>>
>> An issue I can think of with this approach is some how annotating or referencing
that parts of the documentation only work with ${version}. For example new features would
have to be noted they only work with ${version}+.
>>
>>
>> Approach 2:
>> Essentially he same as approach 1 only do allow different Confluence projects for
the different Java EE target version. So WIldFly 8, 9 and 10 would all be documented under
something like WFLYEE7.
>>
>> Approach 3
>> Switch to using something like asciidoc which can use variables and generate
links to the correct content. While this approach is probably takes the most work up
front, it seems like like it would be easier to maintain between releases.
>>
>> Any other suggestions are welcome.
>>
>> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
<https://docs.jboss.org/author/display/WFLY10/Documentation>
>>
>> --
>> James R. Perkins
>> JBoss by Red Hat
>> _______________________________________________
>> wildfly-dev mailing list
>> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
<https://lists.jboss.org/mailman/listinfo/wildfly-dev>
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Jason T. Greene
WildFly Lead / JBoss EAP Platform Architect
JBoss, a division of Red Hat
8:15 p.m.
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 <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
> I've been reading the WildFly documentation [1] quite a bit lately and
> noticing a lot of issues. Sometimes it references WildFly 8 in the
> WildFly 10 (or 9) documentation. Sometimes it references JBoss AS 7.
> Links take you to old documentation, e.g. a WFLY10 doc takes you to a
> page for WFLY8. Sometimes documentation is just plain out of date
> referencing behavior that has possibly been removed or replaced by
> something better.
>
> This has happened because we keep copying the documentation over each
> time we have a new version. Overall this makes sense as a lot of it
> doesn't need to be changed. However it leaves reading the
> documentation confusing. Reading documentation for WildFly 10 and
> seeing WildFly 8 in the text with a link for AS72 isn't very user
> friendly as I'm sure we can all agree.
>
> There's a few different ways we could go with this.
>
> Approach 1:
> One, probably the easiest, is to use a single confluence project. We'd
> need to remove the version numbers from the text, which I think we
> should do anyway. Instead of referencing WildFly 10 we just reference
> it as WildFly.
>
> An issue I can think of with this approach is some how annotating or
> referencing that parts of the documentation only work with ${version}.
> For example new features would have to be noted they only work with
> ${version}+.
>
>
> Approach 2:
> Essentially he same as approach 1 only do allow different Confluence
> projects for the different Java EE target version. So WIldFly 8, 9 and
> 10 would all be documented under something like WFLYEE7.
>
> Approach 3
> Switch to using something like asciidoc which can use variables and
> generate links to the correct content. While this approach is probably
> takes the most work up front, it seems like like it would be easier to
> maintain between releases.
>
> Any other suggestions are welcome.
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>
> --
> James R. Perkins
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
8:20 p.m.
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 <jason.greene(a)redhat.com>
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 <jperkins(a)redhat.com> 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 <jason.greene(a)redhat.com
> 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 <jason.greene(a)redhat.com>
> 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 <jperkins(a)redhat.com> wrote:
>
> I've been reading the WildFly documentation [1] quite a bit lately and
> noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly
> 10 (or 9) documentation. Sometimes it references JBoss AS 7. Links take you
> to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.
> Sometimes documentation is just plain out of date referencing behavior that
> has possibly been removed or replaced by something better.
>
> This has happened because we keep copying the documentation over each
> time we have a new version. Overall this makes sense as a lot of it doesn't
> need to be changed. However it leaves reading the documentation confusing.
> Reading documentation for WildFly 10 and seeing WildFly 8 in the text with
> a link for AS72 isn't very user friendly as I'm sure we can all agree.
>
> There's a few different ways we could go with this.
>
> Approach 1:
> One, probably the easiest, is to use a single confluence project. We'd
> need to remove the version numbers from the text, which I think we should
> do anyway. Instead of referencing WildFly 10 we just reference it as
> WildFly.
>
> An issue I can think of with this approach is some how annotating or
> referencing that parts of the documentation only work with ${version}. For
> example new features would have to be noted they only work with ${version}+.
>
>
> Approach 2:
> Essentially he same as approach 1 only do allow different Confluence
> projects for the different Java EE target version. So WIldFly 8, 9 and 10
> would all be documented under something like WFLYEE7.
>
> Approach 3
> Switch to using something like asciidoc which can use variables and
> generate links to the correct content. While this approach is probably
> takes the most work up front, it seems like like it would be easier to
> maintain between releases.
>
> Any other suggestions are welcome.
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>
> --
> James R. Perkins
> JBoss by Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
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
8:45 p.m.
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 <jason.greene(a)redhat.com
<mailto:jason.greene@redhat.com>> 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 <jperkins(a)redhat.com
> <mailto:jperkins@redhat.com>> 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
> <jason.greene(a)redhat.com <mailto:jason.greene@redhat.com>> 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
> <jason.greene(a)redhat.com <mailto:jason.greene@redhat.com>>
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
>> <jperkins(a)redhat.com <mailto:jperkins@redhat.com>> wrote:
>>
>>> I've been reading the WildFly documentation [1] quite a bit
>>> lately and noticing a lot of issues. Sometimes it references
>>> WildFly 8 in the WildFly 10 (or 9) documentation. Sometimes
>>> it references JBoss AS 7. Links take you to old
>>> documentation, e.g. a WFLY10 doc takes you to a page for
>>> WFLY8. Sometimes documentation is just plain out of date
>>> referencing behavior that has possibly been removed or
>>> replaced by something better.
>>>
>>> This has happened because we keep copying the documentation
>>> over each time we have a new version. Overall this makes
>>> sense as a lot of it doesn't need to be changed. However it
>>> leaves reading the documentation confusing. Reading
>>> documentation for WildFly 10 and seeing WildFly 8 in the
>>> text with a link for AS72 isn't very user friendly as I'm
>>> sure we can all agree.
>>>
>>> There's a few different ways we could go with this.
>>>
>>> Approach 1:
>>> One, probably the easiest, is to use a single confluence
>>> project. We'd need to remove the version numbers from the
>>> text, which I think we should do anyway. Instead of
>>> referencing WildFly 10 we just reference it as WildFly.
>>>
>>> An issue I can think of with this approach is some how
>>> annotating or referencing that parts of the documentation
>>> only work with ${version}. For example new features would
>>> have to be noted they only work with ${version}+.
>>>
>>>
>>> Approach 2:
>>> Essentially he same as approach 1 only do allow different
>>> Confluence projects for the different Java EE target
>>> version. So WIldFly 8, 9 and 10 would all be documented
>>> under something like WFLYEE7.
>>>
>>> Approach 3
>>> Switch to using something like asciidoc which can use
>>> variables and generate links to the correct content. While
>>> this approach is probably takes the most work up front, it
>>> seems like like it would be easier to maintain between releases.
>>>
>>> Any other suggestions are welcome.
>>>
>>> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>>>
>>> --
>>> James R. Perkins
>>> JBoss by Red Hat
>>> _______________________________________________
>>> wildfly-dev mailing list
>>> wildfly-dev(a)lists.jboss.org
<mailto:wildfly-dev@lists.jboss.org>
>>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> James R. Perkins
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> 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
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
10:01 p.m.
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 <jason.greene(a)redhat.com
> <mailto:jason.greene@redhat.com>> 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 <jperkins(a)redhat.com
>> <mailto:jperkins@redhat.com>> 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
>> <jason.greene(a)redhat.com <mailto:jason.greene@redhat.com>>
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
>> <jason.greene(a)redhat.com <mailto:jason.greene@redhat.com>>
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
>>> <jperkins(a)redhat.com <mailto:jperkins@redhat.com>>
wrote:
>>>
>>>> I've been reading the WildFly documentation [1] quite a bit
>>>> lately and noticing a lot of issues. Sometimes it references
>>>> WildFly 8 in the WildFly 10 (or 9) documentation. Sometimes
>>>> it references JBoss AS 7. Links take you to old
>>>> documentation, e.g. a WFLY10 doc takes you to a page for
>>>> WFLY8. Sometimes documentation is just plain out of date
>>>> referencing behavior that has possibly been removed or
>>>> replaced by something better.
>>>>
>>>> This has happened because we keep copying the documentation
>>>> over each time we have a new version. Overall this makes
>>>> sense as a lot of it doesn't need to be changed. However it
>>>> leaves reading the documentation confusing. Reading
>>>> documentation for WildFly 10 and seeing WildFly 8 in the
>>>> text with a link for AS72 isn't very user friendly as
I'm
>>>> sure we can all agree.
>>>>
>>>> There's a few different ways we could go with this.
>>>>
>>>> Approach 1:
>>>> One, probably the easiest, is to use a single confluence
>>>> project. We'd need to remove the version numbers from the
>>>> text, which I think we should do anyway. Instead of
>>>> referencing WildFly 10 we just reference it as WildFly.
>>>>
>>>> An issue I can think of with this approach is some how
>>>> annotating or referencing that parts of the documentation
>>>> only work with ${version}. For example new features would
>>>> have to be noted they only work with ${version}+.
>>>>
>>>>
>>>> Approach 2:
>>>> Essentially he same as approach 1 only do allow different
>>>> Confluence projects for the different Java EE target
>>>> version. So WIldFly 8, 9 and 10 would all be documented
>>>> under something like WFLYEE7.
>>>>
>>>> Approach 3
>>>> Switch to using something like asciidoc which can use
>>>> variables and generate links to the correct content. While
>>>> this approach is probably takes the most work up front, it
>>>> seems like like it would be easier to maintain between
releases.
>>>>
>>>> Any other suggestions are welcome.
>>>>
>>>> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>>>>
>>>> --
>>>> James R. Perkins
>>>> JBoss by Red Hat
>>>> _______________________________________________
>>>> wildfly-dev mailing list
>>>> wildfly-dev(a)lists.jboss.org
<mailto:wildfly-dev@lists.jboss.org>
>>>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>>
>>
>>
>>
>> --
>> James R. Perkins
>> JBoss by Red Hat
>> _______________________________________________
>> wildfly-dev mailing list
>> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
>> 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
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
- DML
10:26 p.m.
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 <david.lloyd(a)redhat.com
<mailto:david.lloyd@redhat.com>> 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
> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
--
- DML
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Brian Stansberry
Senior Principal Software Engineer
JBoss by Red Hat
11:28 p.m.
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 <
brian.stansberry(a)redhat.com> 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 <david.lloyd(a)redhat.com
> <mailto:david.lloyd@redhat.com>> 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
> > wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> >
>
> --
> - DML
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> James R. Perkins
> JBoss by Red Hat
>
>
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
--
Brian Stansberry
Senior Principal Software Engineer
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
11:08 a.m.
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 <
brian.stansberry(a)redhat.com > 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 < david.lloyd(a)redhat.com
> <mailto: david.lloyd(a)redhat.com >> 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
> > wildfly-dev(a)lists.jboss.org <mailto: wildfly-dev(a)lists.jboss.org >
> > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> >
>
> --
> - DML
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org <mailto: wildfly-dev(a)lists.jboss.org >
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
>
> --
> James R. Perkins
> JBoss by Red Hat
>
>
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
--
Brian Stansberry
Senior Principal Software Engineer
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
7:45 p.m.
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" <rsvoboda(a)redhat.com> 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 <
> brian.stansberry(a)redhat.com > 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 <
david.lloyd(a)redhat.com
> > <mailto: david.lloyd(a)redhat.com >> 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
> > > wildfly-dev(a)lists.jboss.org <mailto: wildfly-dev(a)lists.jboss.org >
> > > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> > >
> >
> > --
> > - DML
> > _______________________________________________
> > wildfly-dev mailing list
> > wildfly-dev(a)lists.jboss.org <mailto: wildfly-dev(a)lists.jboss.org >
> > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> >
> >
> >
> >
> > --
> > James R. Perkins
> > JBoss by Red Hat
> >
> >
> > _______________________________________________
> > wildfly-dev mailing list
> > wildfly-dev(a)lists.jboss.org
> > https://lists.jboss.org/mailman/listinfo/wildfly-dev
> >
>
>
> --
> Brian Stansberry
> Senior Principal Software Engineer
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
>
> --
> James R. Perkins
> JBoss by Red Hat
>
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
6:37 p.m.
So what are we going to do about this?
We’ve now reached the point where we need to start generating documentation for WildFly
11. And we’re beginning to require devs, at least those working for Red Hat, to write some
sort of community doc as part of getting RFEs resolved. So docs infrastructure issue are
beginning to impact our ability to get code changes in.
My 2 cents: an asciidoctor and git based approach sounds good, but unless we have
resources available to make it happen quickly basically starting from today, we need to
devise a strategy based on continuing to use confluence.
The biggest problem I saw in James’ original post was "Links take you to old
documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.” If that’s an inherent
problem in cloning docs it’s hard to deal with. Having a living document isn’t so hard;
you just write as if it’s a living doc and say things like “Since WildFly 10” etc. But if
you can’t snapshot the living doc for a release without creating a lot of bad links,
that’s a problem.
On May 12, 2016, at 10:32 PM, James Perkins
<jperkins(a)redhat.com> wrote:
I've been reading the WildFly documentation [1] quite a bit lately and noticing a lot
of issues. Sometimes it references WildFly 8 in the WildFly 10 (or 9) documentation.
Sometimes it references JBoss AS 7. Links take you to old documentation, e.g. a WFLY10 doc
takes you to a page for WFLY8. Sometimes documentation is just plain out of date
referencing behavior that has possibly been removed or replaced by something better.
This has happened because we keep copying the documentation over each time we have a new
version. Overall this makes sense as a lot of it doesn't need to be changed. However
it leaves reading the documentation confusing. Reading documentation for WildFly 10 and
seeing WildFly 8 in the text with a link for AS72 isn't very user friendly as I'm
sure we can all agree.
There's a few different ways we could go with this.
Approach 1:
One, probably the easiest, is to use a single confluence project. We'd need to remove
the version numbers from the text, which I think we should do anyway. Instead of
referencing WildFly 10 we just reference it as WildFly.
An issue I can think of with this approach is some how annotating or referencing that
parts of the documentation only work with ${version}. For example new features would have
to be noted they only work with ${version}+.
Approach 2:
Essentially he same as approach 1 only do allow different Confluence projects for the
different Java EE target version. So WIldFly 8, 9 and 10 would all be documented under
something like WFLYEE7.
Approach 3
Switch to using something like asciidoc which can use variables and generate links to the
correct content. While this approach is probably takes the most work up front, it seems
like like it would be easier to maintain between releases.
Any other suggestions are welcome.
[1]: https://docs.jboss.org/author/display/WFLY10/Documentation
<https://docs.jboss.org/author/display/WFLY10/Documentation>
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by Red Hat
7:10 p.m.
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-...
[2]:
https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+R...
On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <
brian.stansberry(a)redhat.com> wrote:
So what are we going to do about this?
We’ve now reached the point where we need to start generating
documentation for WildFly 11. And we’re beginning to require devs, at least
those working for Red Hat, to write some sort of community doc as part of
getting RFEs resolved. So docs infrastructure issue are beginning to impact
our ability to get code changes in.
My 2 cents: an asciidoctor and git based approach sounds good, but unless
we have resources available to make it happen quickly basically starting
from today, we need to devise a strategy based on continuing to use
confluence.
The biggest problem I saw in James’ original post was "Links take you to
old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.” If
that’s an inherent problem in cloning docs it’s hard to deal with. Having a
living document isn’t so hard; you just write as if it’s a living doc and
say things like “Since WildFly 10” etc. But if you can’t snapshot the
living doc for a release without creating a lot of bad links, that’s a
problem.
On May 12, 2016, at 10:32 PM, James Perkins <jperkins(a)redhat.com> wrote:
I've been reading the WildFly documentation [1] quite a bit lately and
noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly
10 (or 9) documentation. Sometimes it references JBoss AS 7. Links take you
to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.
Sometimes documentation is just plain out of date referencing behavior that
has possibly been removed or replaced by something better.
This has happened because we keep copying the documentation over each time
we have a new version. Overall this makes sense as a lot of it doesn't need
to be changed. However it leaves reading the documentation confusing.
Reading documentation for WildFly 10 and seeing WildFly 8 in the text with
a link for AS72 isn't very user friendly as I'm sure we can all agree.
There's a few different ways we could go with this.
Approach 1:
One, probably the easiest, is to use a single confluence project. We'd
need to remove the version numbers from the text, which I think we should
do anyway. Instead of referencing WildFly 10 we just reference it as
WildFly.
An issue I can think of with this approach is some how annotating or
referencing that parts of the documentation only work with ${version}. For
example new features would have to be noted they only work with ${version}+.
Approach 2:
Essentially he same as approach 1 only do allow different Confluence
projects for the different Java EE target version. So WIldFly 8, 9 and 10
would all be documented under something like WFLYEE7.
Approach 3
Switch to using something like asciidoc which can use variables and
generate links to the correct content. While this approach is probably
takes the most work up front, it seems like like it would be easier to
maintain between releases.
Any other suggestions are welcome.
[1]: https://docs.jboss.org/author/display/WFLY10/Documentation
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by Red Hat
--
James R. Perkins
JBoss by Red Hat
7:40 p.m.
Just one more follow as Tomaz mentioned to me, another option would be
https://www.gitbook.com/. Both WildFly Swarm [1] and JBeret [2] use it.
[1]: https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/
[2]: https://jberet.gitbooks.io/jberet-user-guide/content/
On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <jperkins(a)redhat.com> wrote:
Thanks for bringing this back up Brian. I was just about to do the
same :)
The only idea I'm personally opposed to is the "fork for every release"
Though thinking of it as a live doc where we snapshot it for a release is
not a bad idea. We could just have a WFLY project that we snapshot for
every release. We just need to be careful about using versioning when
writing the docs, unless it's a "Since WIldFly whatever" type of thing. We
just want to avoid the "In WildFly x".
With regards to the linking problem, I'm not sure if we (myself included)
are just linking incorrectly between documents or it's just a limitation of
Confluence. It looks like most links are done like [WFLY8:Implicit module
dependencies for deployments]. I noticed some don't have the
"WFLY${version}" prefix so maybe that's the way to go. When you use the
linking function in confluence it adds the doc reference to the link which
could be part of the problem.
There are also docs that just point to old information. Like the main page
references Java EE 6 getting started [1]. The Some pages are just dead too
[2]. In some places, I tried to fix the ones I found in the WFLY10 docs, it
just references the wrong version of WildFly. A lot of XML references too
which likely point to older namespaces, maybe not a huge deal though.
Overall they're not bad. They just need a little TLC. I do think too there
is probably some bigger chunks we can get rid of like a lot of the
quickstart section since we have it all on GitHub. Also subsystem
references could be replaced with WildScribe.
Anyway, I'm up for anything that allows the documentation to be
consistent, easy to write and easy to use. The main attraction for me to
asciidoc is being able to use git for versioning as well as being able to
use variables. I don't however know how well asciidoc deals with multiple
documents and combining them together.
Regardless of the direction I'm willing to put some time into
fixing/updating it. I just think before we invest any time we make a firm
decision on the direction we want to go.
[1]:
https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-...
[2]:
https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+R...
On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <
brian.stansberry(a)redhat.com> wrote:
> So what are we going to do about this?
>
> We’ve now reached the point where we need to start generating
> documentation for WildFly 11. And we’re beginning to require devs, at least
> those working for Red Hat, to write some sort of community doc as part of
> getting RFEs resolved. So docs infrastructure issue are beginning to impact
> our ability to get code changes in.
>
> My 2 cents: an asciidoctor and git based approach sounds good, but unless
> we have resources available to make it happen quickly basically starting
> from today, we need to devise a strategy based on continuing to use
> confluence.
>
> The biggest problem I saw in James’ original post was "Links take you to
> old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.” If
> that’s an inherent problem in cloning docs it’s hard to deal with. Having a
> living document isn’t so hard; you just write as if it’s a living doc and
> say things like “Since WildFly 10” etc. But if you can’t snapshot the
> living doc for a release without creating a lot of bad links, that’s a
> problem.
>
> On May 12, 2016, at 10:32 PM, James Perkins <jperkins(a)redhat.com> wrote:
>
> I've been reading the WildFly documentation [1] quite a bit lately and
> noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly
> 10 (or 9) documentation. Sometimes it references JBoss AS 7. Links take you
> to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.
> Sometimes documentation is just plain out of date referencing behavior that
> has possibly been removed or replaced by something better.
>
> This has happened because we keep copying the documentation over each
> time we have a new version. Overall this makes sense as a lot of it doesn't
> need to be changed. However it leaves reading the documentation confusing.
> Reading documentation for WildFly 10 and seeing WildFly 8 in the text with
> a link for AS72 isn't very user friendly as I'm sure we can all agree.
>
> There's a few different ways we could go with this.
>
> Approach 1:
> One, probably the easiest, is to use a single confluence project. We'd
> need to remove the version numbers from the text, which I think we should
> do anyway. Instead of referencing WildFly 10 we just reference it as
> WildFly.
>
> An issue I can think of with this approach is some how annotating or
> referencing that parts of the documentation only work with ${version}. For
> example new features would have to be noted they only work with ${version}+.
>
>
> Approach 2:
> Essentially he same as approach 1 only do allow different Confluence
> projects for the different Java EE target version. So WIldFly 8, 9 and 10
> would all be documented under something like WFLYEE7.
>
> Approach 3
> Switch to using something like asciidoc which can use variables and
> generate links to the correct content. While this approach is probably
> takes the most work up front, it seems like like it would be easier to
> maintain between releases.
>
> Any other suggestions are welcome.
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>
> --
> James R. Perkins
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> JBoss by Red Hat
>
>
>
>
--
James R. Perkins
JBoss by Red Hat
--
James R. Perkins
JBoss by Red Hat
7:57 p.m.
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 <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
Thanks for bringing this back up Brian. I was just about to do the same :)
The only idea I'm personally opposed to is the "fork for every release"
Though thinking of it as a live doc where we snapshot it for a
release is not a bad idea. We could just have a WFLY project that we snapshot for
every release. We just need to be careful about using
versioning when writing the docs, unless it's a "Since WIldFly
whatever" type of thing. We just want to avoid the "In WildFly x".
With regards to the linking problem, I'm not sure if we (myself included) are
just linking incorrectly between documents or it's just a
limitation of Confluence. It looks like most links are done like [WFLY8:Implicit
module dependencies for deployments]. I noticed some
don't have the "WFLY${version}" prefix so maybe that's the way to
go. When you use the linking function in confluence it adds the doc
reference to the link which could be part of the problem.
There are also docs that just point to old information. Like the main page references
Java EE 6 getting started [1]. The Some pages are
just dead too [2]. In some places, I tried to fix the ones I found in the WFLY10
docs, it just references the wrong version of WildFly.
A lot of XML references too which likely point to older namespaces, maybe not a huge
deal though.
Overall they're not bad. They just need a little TLC. I do think too there is
probably some bigger chunks we can get rid of like a lot
of the quickstart section since we have it all on GitHub. Also subsystem references
could be replaced with WildScribe.
Anyway, I'm up for anything that allows the documentation to be consistent, easy
to write and easy to use. The main attraction for me to
asciidoc is being able to use git for versioning as well as being able to use
variables. I don't however know how well asciidoc deals
with multiple documents and combining them together.
Regardless of the direction I'm willing to put some time into fixing/updating it.
I just think before we invest any time we make a firm
decision on the direction we want to go.
[1]:
https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-...
[2]:
https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+R...
On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <brian.stansberry(a)redhat.com
<mailto:brian.stansberry@redhat.com>> wrote:
So what are we going to do about this?
We’ve now reached the point where we need to start generating documentation for
WildFly 11. And we’re beginning to require devs, at
least those working for Red Hat, to write some sort of community doc as part of
getting RFEs resolved. So docs infrastructure issue
are beginning to impact our ability to get code changes in.
My 2 cents: an asciidoctor and git based approach sounds good, but unless we have
resources available to make it happen quickly
basically starting from today, we need to devise a strategy based on continuing
to use confluence.
The biggest problem I saw in James’ original post was "Links take you to old
documentation, e.g. a WFLY10 doc takes you to a page
for WFLY8.” If that’s an inherent problem in cloning docs it’s hard to deal with.
Having a living document isn’t so hard; you just
write as if it’s a living doc and say things like “Since WildFly 10” etc. But if
you can’t snapshot the living doc for a release
without creating a lot of bad links, that’s a problem.
> On May 12, 2016, at 10:32 PM, James Perkins <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
>
> I've been reading the WildFly documentation [1] quite a bit lately and
noticing a lot of issues. Sometimes it references WildFly 8
> in the WildFly 10 (or 9) documentation. Sometimes it references JBoss AS 7.
Links take you to old documentation, e.g. a WFLY10 doc
> takes you to a page for WFLY8. Sometimes documentation is just plain out of
date referencing behavior that has possibly been
> removed or replaced by something better.
>
> This has happened because we keep copying the documentation over each time we
have a new version. Overall this makes sense as a
> lot of it doesn't need to be changed. However it leaves reading the
documentation confusing. Reading documentation for WildFly 10
> and seeing WildFly 8 in the text with a link for AS72 isn't very user
friendly as I'm sure we can all agree.
>
> There's a few different ways we could go with this.
>
> Approach 1:
> One, probably the easiest, is to use a single confluence project. We'd
need to remove the version numbers from the text, which I
> think we should do anyway. Instead of referencing WildFly 10 we just
reference it as WildFly.
>
> An issue I can think of with this approach is some how annotating or
referencing that parts of the documentation only work with
> ${version}. For example new features would have to be noted they only work
with ${version}+.
>
>
> Approach 2:
> Essentially he same as approach 1 only do allow different Confluence projects
for the different Java EE target version. So WIldFly
> 8, 9 and 10 would all be documented under something like WFLYEE7.
>
> Approach 3
> Switch to using something like asciidoc which can use variables and generate
links to the correct content. While this approach is
> probably takes the most work up front, it seems like like it would be easier
to maintain between releases.
>
> Any other suggestions are welcome.
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>
> --
> James R. Perkins
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by Red Hat
--
James R. Perkins
JBoss by Red Hat
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
8:46 p.m.
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
http://wildfly-swarm.io/documentation/
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 <jperkins(a)redhat.com> 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 <jperkins(a)redhat.com>
wrote:
> Thanks for bringing this back up Brian. I was just about to do the same :)
>
> The only idea I'm personally opposed to is the "fork for every
release"
> Though thinking of it as a live doc where we snapshot it for a release is
> not a bad idea. We could just have a WFLY project that we snapshot for
> every release. We just need to be careful about using versioning when
> writing the docs, unless it's a "Since WIldFly whatever" type of thing.
We
> just want to avoid the "In WildFly x".
>
> With regards to the linking problem, I'm not sure if we (myself included)
> are just linking incorrectly between documents or it's just a limitation of
> Confluence. It looks like most links are done like [WFLY8:Implicit module
> dependencies for deployments]. I noticed some don't have the
> "WFLY${version}" prefix so maybe that's the way to go. When you use
the
> linking function in confluence it adds the doc reference to the link which
> could be part of the problem.
>
> There are also docs that just point to old information. Like the main
> page references Java EE 6 getting started [1]. The Some pages are just
> dead too [2]. In some places, I tried to fix the ones I found in the WFLY10
> docs, it just references the wrong version of WildFly. A lot of XML
> references too which likely point to older namespaces, maybe not a huge
> deal though.
>
> Overall they're not bad. They just need a little TLC. I do think too
> there is probably some bigger chunks we can get rid of like a lot of the
> quickstart section since we have it all on GitHub. Also subsystem
> references could be replaced with WildScribe.
>
> Anyway, I'm up for anything that allows the documentation to be
> consistent, easy to write and easy to use. The main attraction for me to
> asciidoc is being able to use git for versioning as well as being able to
> use variables. I don't however know how well asciidoc deals with multiple
> documents and combining them together.
>
> Regardless of the direction I'm willing to put some time into
> fixing/updating it. I just think before we invest any time we make a firm
> decision on the direction we want to go.
>
>
> [1]:
>
https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-...
> [2]:
>
https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+R...
>
> On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <
> brian.stansberry(a)redhat.com> wrote:
>
>> So what are we going to do about this?
>>
>> We’ve now reached the point where we need to start generating
>> documentation for WildFly 11. And we’re beginning to require devs, at least
>> those working for Red Hat, to write some sort of community doc as part of
>> getting RFEs resolved. So docs infrastructure issue are beginning to impact
>> our ability to get code changes in.
>>
>> My 2 cents: an asciidoctor and git based approach sounds good, but
>> unless we have resources available to make it happen quickly basically
>> starting from today, we need to devise a strategy based on continuing to
>> use confluence.
>>
>> The biggest problem I saw in James’ original post was "Links take you to
>> old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.” If
>> that’s an inherent problem in cloning docs it’s hard to deal with. Having a
>> living document isn’t so hard; you just write as if it’s a living doc and
>> say things like “Since WildFly 10” etc. But if you can’t snapshot the
>> living doc for a release without creating a lot of bad links, that’s a
>> problem.
>>
>> On May 12, 2016, at 10:32 PM, James Perkins <jperkins(a)redhat.com> wrote:
>>
>> I've been reading the WildFly documentation [1] quite a bit lately and
>> noticing a lot of issues. Sometimes it references WildFly 8 in the WildFly
>> 10 (or 9) documentation. Sometimes it references JBoss AS 7. Links take you
>> to old documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.
>> Sometimes documentation is just plain out of date referencing behavior that
>> has possibly been removed or replaced by something better.
>>
>> This has happened because we keep copying the documentation over each
>> time we have a new version. Overall this makes sense as a lot of it doesn't
>> need to be changed. However it leaves reading the documentation confusing.
>> Reading documentation for WildFly 10 and seeing WildFly 8 in the text with
>> a link for AS72 isn't very user friendly as I'm sure we can all agree.
>>
>> There's a few different ways we could go with this.
>>
>> Approach 1:
>> One, probably the easiest, is to use a single confluence project. We'd
>> need to remove the version numbers from the text, which I think we should
>> do anyway. Instead of referencing WildFly 10 we just reference it as
>> WildFly.
>>
>> An issue I can think of with this approach is some how annotating or
>> referencing that parts of the documentation only work with ${version}. For
>> example new features would have to be noted they only work with ${version}+.
>>
>>
>> Approach 2:
>> Essentially he same as approach 1 only do allow different Confluence
>> projects for the different Java EE target version. So WIldFly 8, 9 and 10
>> would all be documented under something like WFLYEE7.
>>
>> Approach 3
>> Switch to using something like asciidoc which can use variables and
>> generate links to the correct content. While this approach is probably
>> takes the most work up front, it seems like like it would be easier to
>> maintain between releases.
>>
>> Any other suggestions are welcome.
>>
>> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
>>
>> --
>> James R. Perkins
>> JBoss by Red Hat
>> _______________________________________________
>> wildfly-dev mailing list
>> wildfly-dev(a)lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>>
>>
>> --
>> Brian Stansberry
>> Manager, Senior Principal Software Engineer
>> JBoss by Red Hat
>>
>>
>>
>>
>
>
> --
> James R. Perkins
> JBoss by Red Hat
>
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
8:46 p.m.
On Mon, Jul 25, 2016 at 10:57 AM, Emmanuel Hugonnet <ehugonne(a)redhat.com>
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
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
10:52 p.m.
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
<bmcwhirt(a)redhat.com> 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
http://wildfly-swarm.io/documentation/ <http://wildfly-swarm.io/documentation/>
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 <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
Just one more follow as Tomaz mentioned to me, another option would be
https://www.gitbook.com/ <https://www.gitbook.com/>;. Both WildFly Swarm [1] and
JBeret [2] use it.
[1]: https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/
<https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/>
[2]: https://jberet.gitbooks.io/jberet-user-guide/content/
<https://jberet.gitbooks.io/jberet-user-guide/content/>
On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
Thanks for bringing this back up Brian. I was just about to do the same :)
The only idea I'm personally opposed to is the "fork for every release"
Though thinking of it as a live doc where we snapshot it for a release is not a bad idea.
We could just have a WFLY project that we snapshot for every release. We just need to be
careful about using versioning when writing the docs, unless it's a "Since
WIldFly whatever" type of thing. We just want to avoid the "In WildFly x".
With regards to the linking problem, I'm not sure if we (myself included) are just
linking incorrectly between documents or it's just a limitation of Confluence. It
looks like most links are done like [WFLY8:Implicit module dependencies for deployments].
I noticed some don't have the "WFLY${version}" prefix so maybe that's
the way to go. When you use the linking function in confluence it adds the doc reference
to the link which could be part of the problem.
There are also docs that just point to old information. Like the main page references
Java EE 6 getting started [1]. The Some pages are just dead too [2]. In some places, I
tried to fix the ones I found in the WFLY10 docs, it just references the wrong version of
WildFly. A lot of XML references too which likely point to older namespaces, maybe not a
huge deal though.
Overall they're not bad. They just need a little TLC. I do think too there is
probably some bigger chunks we can get rid of like a lot of the quickstart section since
we have it all on GitHub. Also subsystem references could be replaced with WildScribe.
Anyway, I'm up for anything that allows the documentation to be consistent, easy to
write and easy to use. The main attraction for me to asciidoc is being able to use git for
versioning as well as being able to use variables. I don't however know how well
asciidoc deals with multiple documents and combining them together.
Regardless of the direction I'm willing to put some time into fixing/updating it. I
just think before we invest any time we make a firm decision on the direction we want to
go.
[1]:
https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-...
<https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-...
[2]:
https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+R...
<https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+R...
On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <brian.stansberry(a)redhat.com
<mailto:brian.stansberry@redhat.com>> wrote:
So what are we going to do about this?
We’ve now reached the point where we need to start generating documentation for WildFly
11. And we’re beginning to require devs, at least those working for Red Hat, to write some
sort of community doc as part of getting RFEs resolved. So docs infrastructure issue are
beginning to impact our ability to get code changes in.
My 2 cents: an asciidoctor and git based approach sounds good, but unless we have
resources available to make it happen quickly basically starting from today, we need to
devise a strategy based on continuing to use confluence.
The biggest problem I saw in James’ original post was "Links take you to old
documentation, e.g. a WFLY10 doc takes you to a page for WFLY8.” If that’s an inherent
problem in cloning docs it’s hard to deal with. Having a living document isn’t so hard;
you just write as if it’s a living doc and say things like “Since WildFly 10” etc. But if
you can’t snapshot the living doc for a release without creating a lot of bad links,
that’s a problem.
> On May 12, 2016, at 10:32 PM, James Perkins <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
>
> I've been reading the WildFly documentation [1] quite a bit lately and noticing a
lot of issues. Sometimes it references WildFly 8 in the WildFly 10 (or 9) documentation.
Sometimes it references JBoss AS 7. Links take you to old documentation, e.g. a WFLY10 doc
takes you to a page for WFLY8. Sometimes documentation is just plain out of date
referencing behavior that has possibly been removed or replaced by something better.
>
> This has happened because we keep copying the documentation over each time we have a
new version. Overall this makes sense as a lot of it doesn't need to be changed.
However it leaves reading the documentation confusing. Reading documentation for WildFly
10 and seeing WildFly 8 in the text with a link for AS72 isn't very user friendly as
I'm sure we can all agree.
>
> There's a few different ways we could go with this.
>
> Approach 1:
> One, probably the easiest, is to use a single confluence project. We'd need to
remove the version numbers from the text, which I think we should do anyway. Instead of
referencing WildFly 10 we just reference it as WildFly.
>
> An issue I can think of with this approach is some how annotating or referencing that
parts of the documentation only work with ${version}. For example new features would have
to be noted they only work with ${version}+.
>
>
> Approach 2:
> Essentially he same as approach 1 only do allow different Confluence projects for the
different Java EE target version. So WIldFly 8, 9 and 10 would all be documented under
something like WFLYEE7.
>
> Approach 3
> Switch to using something like asciidoc which can use variables and generate links to
the correct content. While this approach is probably takes the most work up front, it
seems like like it would be easier to maintain between releases.
>
> Any other suggestions are welcome.
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
<https://docs.jboss.org/author/display/WFLY10/Documentation>
>
> --
> James R. Perkins
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
<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
wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
https://lists.jboss.org/mailman/listinfo/wildfly-dev
<https://lists.jboss.org/mailman/listinfo/wildfly-dev>
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by Red Hat
11:56 p.m.
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
<tomaz.cerar(a)gmail.com> wrote:
On Mon, Jul 25, 2016 at 10:52 PM, Brian Stansberry <brian.stansberry(a)redhat.com
<mailto:brian.stansberry@redhat.com>> 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
7:54 a.m.
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
<brian.stansberry(a)redhat.com>:
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 <tomaz.cerar(a)gmail.com> wrote:
>
>
>> On Mon, Jul 25, 2016 at 10:52 PM, Brian Stansberry
<brian.stansberry(a)redhat.com> 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
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
12:51 a.m.
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
<ehugonne(a)redhat.com <mailto:ehugonne@redhat.com>> 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
wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Richard Opalka
Principal Software Engineer
Red Hat JBoss Middleware
Mobile: +420 731 186 942
E-mail: ropalka(a)redhat.com
3:42 p.m.
On Jul 25, 2016, at 1:40 PM, James Perkins <jperkins(a)redhat.com> 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
7:16 p.m.
On Fri, Jul 29, 2016 at 6:42 AM, Carl Harris <ceharris414(a)me.com> wrote:
On Jul 25, 2016, at 1:40 PM, James Perkins <jperkins(a)redhat.com> 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
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
James R. Perkins
JBoss by Red Hat
7:55 p.m.
On Jul 29, 2016, at 1:16 PM, James Perkins
<jperkins(a)redhat.com> wrote:
On Fri, Jul 29, 2016 at 6:42 AM, Carl Harris <ceharris414(a)me.com
<mailto:ceharris414@me.com>> 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
9:54 p.m.
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
<jperkins(a)redhat.com> wrote:
I've been reading the WildFly documentation [1] quite a bit lately and noticing a lot
of issues. Sometimes it references WildFly 8 in the WildFly 10 (or 9) documentation.
Sometimes it references JBoss AS 7. Links take you to old documentation, e.g. a WFLY10 doc
takes you to a page for WFLY8. Sometimes documentation is just plain out of date
referencing behavior that has possibly been removed or replaced by something better.
This has happened because we keep copying the documentation over each time we have a new
version. Overall this makes sense as a lot of it doesn't need to be changed. However
it leaves reading the documentation confusing. Reading documentation for WildFly 10 and
seeing WildFly 8 in the text with a link for AS72 isn't very user friendly as I'm
sure we can all agree.
There's a few different ways we could go with this.
Approach 1:
One, probably the easiest, is to use a single confluence project. We'd need to remove
the version numbers from the text, which I think we should do anyway. Instead of
referencing WildFly 10 we just reference it as WildFly.
An issue I can think of with this approach is some how annotating or referencing that
parts of the documentation only work with ${version}. For example new features would have
to be noted they only work with ${version}+.
Approach 2:
Essentially he same as approach 1 only do allow different Confluence projects for the
different Java EE target version. So WIldFly 8, 9 and 10 would all be documented under
something like WFLYEE7.
Approach 3
Switch to using something like asciidoc which can use variables and generate links to the
correct content. While this approach is probably takes the most work up front, it seems
like like it would be easier to maintain between releases.
Any other suggestions are welcome.
[1]: https://docs.jboss.org/author/display/WFLY10/Documentation
<https://docs.jboss.org/author/display/WFLY10/Documentation>
--
James R. Perkins
JBoss by Red Hat
_______________________________________________
wildfly-dev mailing list
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Jason T. Greene
WildFly Lead / JBoss EAP Platform Architect
JBoss, a division of Red Hat
11:23 p.m.
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
https://docs.jboss.org/author/display/WFLY/
<https://docs.jboss.org/author/display/WFLY/>RBAC
and not the WFLY11 snapshot URL:
https://docs.jboss.org/author/display/WFLY11/
<https://docs.jboss.org/author/display/WFLY11/>RBAC
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
<jason.greene(a)redhat.com> 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 <jperkins(a)redhat.com
<mailto:jperkins@redhat.com>> wrote:
>
> I've been reading the WildFly documentation [1] quite a bit lately and noticing a
lot of issues. Sometimes it references WildFly 8 in the WildFly 10 (or 9) documentation.
Sometimes it references JBoss AS 7. Links take you to old documentation, e.g. a WFLY10 doc
takes you to a page for WFLY8. Sometimes documentation is just plain out of date
referencing behavior that has possibly been removed or replaced by something better.
>
> This has happened because we keep copying the documentation over each time we have a
new version. Overall this makes sense as a lot of it doesn't need to be changed.
However it leaves reading the documentation confusing. Reading documentation for WildFly
10 and seeing WildFly 8 in the text with a link for AS72 isn't very user friendly as
I'm sure we can all agree.
>
> There's a few different ways we could go with this.
>
> Approach 1:
> One, probably the easiest, is to use a single confluence project. We'd need to
remove the version numbers from the text, which I think we should do anyway. Instead of
referencing WildFly 10 we just reference it as WildFly.
>
> An issue I can think of with this approach is some how annotating or referencing that
parts of the documentation only work with ${version}. For example new features would have
to be noted they only work with ${version}+.
>
>
> Approach 2:
> Essentially he same as approach 1 only do allow different Confluence projects for the
different Java EE target version. So WIldFly 8, 9 and 10 would all be documented under
something like WFLYEE7.
>
> Approach 3
> Switch to using something like asciidoc which can use variables and generate links to
the correct content. While this approach is probably takes the most work up front, it
seems like like it would be easier to maintain between releases.
>
> Any other suggestions are welcome.
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation
<https://docs.jboss.org/author/display/WFLY10/Documentation>
>
> --
> James R. Perkins
> JBoss by Red Hat
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev(a)lists.jboss.org <mailto:wildfly-dev@lists.jboss.org>
> 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
wildfly-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by Red Hat
2821
days inactive
2898
days old
34 comments
16 participants
participants (16)
-
Bob McWhirter -
Brian Stansberry -
Carl Harris -
David M. Lloyd -
Emmanuel Hugonnet -
Heiko Braun -
Heiko W.Rupp -
James Perkins -
Jason Greene -
Jason T. Greene
-
Nicklas Karlsson -
Richard Opalka -
Rostislav Svoboda -
Sanne Grinovero -
Scott Marlow -
Tomaž Cerar