[wildfly-dev] One Doc to Rule Them All

[David M. Lloyd]

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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>

-- 
- DML