[wildfly-dev] One Doc to Rule Them All
David M. Lloyd
david.lloyd at redhat.com
Fri May 13 16:01:48 EDT 2016
One thing you can do on GitHub is, edit a page in-place, and it will
automatically create a PR for you. This can give the "feel" of a wiki
without sacrificing the control that we need.
On 05/13/2016 01:45 PM, Scott Marlow wrote:
> 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
>>
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>
--
- DML
More information about the wildfly-dev
mailing list