11:37 a.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