[wildfly-dev] One Doc to Rule Them All

[James Perkins]

As David stated one thing I do see as a positive for asciidoc is we could
do PR's. So if we have some big new feature come in we could also request
the submitter to add a docs PR too. That might be asking too much, but it's
nice in theory at least :)

On Fri, May 13, 2016 at 11:12 AM, Jason Greene <jason.greene at redhat.com>
wrote:

> Right well basically what I am saying is that instead of forking at a
> specific point in time, which is really what option 2 is about, we just
> fork when it really becomes necessary, which is likely a major
> re-architecture.
>
> While it does sound like I am advocating 1, 3 could meet this as well. We
> can have one link for “WildFly docs” which is always the most current, and
> if we were using asciidoc, we could have “archived docs”, which are not
> maintained but there for reference if need be.
>
>
> On May 13, 2016, at 12:57 PM, James Perkins <jperkins at redhat.com> wrote:
>
> 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
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
>
> --
> Jason T. Greene
> WildFly Lead / JBoss EAP Platform Architect
> JBoss, a division of Red Hat
>
>


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