[wildfly-dev] One Doc to Rule Them All

[James Perkins]

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


-- 
James R. Perkins
JBoss by Red Hat
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wildfly-dev/attachments/20160513/1cc96d11/attachment.html