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