8:12 a.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