[wildfly-dev] One Doc to Rule Them All

[Scott Marlow]

On 05/13/2016 01:50 PM, Jason T. Greene 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".

This worked well enough in the old JBoss wiki, except it sometimes got 
long (from what I remember).

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