[wildfly-dev] One Doc to Rule Them All
Scott Marlow
smarlow at redhat.com
Fri May 13 14:45:29 EDT 2016
IMO, it would probably be nicer if the GIT repo is open. Requiring a PR
for every doc change, might discourage contributions.
We probably did fork the documentation too often, as contributions
slowed down over time. If developers are less interested in
contributing documentation, we might want to fork less but also keep it
easy to make changes (e.g. use a wiki/confluence or other online editor).
On 05/13/2016 02:20 PM, James Perkins wrote:
> 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
> <mailto: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
>> <mailto: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 <mailto: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 <mailto: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 <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
>>
>>
>>
>>
>> --
>> 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
>
> --
> Jason T. Greene
> WildFly Lead / JBoss EAP Platform Architect
> JBoss, a division of Red Hat
>
>
>
>
> --
> 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
>
More information about the wildfly-dev
mailing list