[wildfly-dev] One Doc to Rule Them All
Emmanuel Hugonnet
ehugonne at redhat.com
Mon Jul 25 13:57:30 EDT 2016
Hi,
Should we have a maintenance branch for the current stable version documentation (maybe on gitbook) and a living documentation (using github
rendering) or just the living doc ?
On 25/07/2016 19:40, James Perkins wrote:
> Just one more follow as Tomaz mentioned to me, another option would be https://www.gitbook.com/. Both WildFly Swarm [1] and JBeret [2] use it.
>
> [1]: https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/
> [2]: https://jberet.gitbooks.io/jberet-user-guide/content/
>
> On Mon, Jul 25, 2016 at 10:10 AM, James Perkins <jperkins at redhat.com <mailto:jperkins at redhat.com>> wrote:
>
> Thanks for bringing this back up Brian. I was just about to do the same :)
>
> The only idea I'm personally opposed to is the "fork for every release" Though thinking of it as a live doc where we snapshot it for a
> release is not a bad idea. We could just have a WFLY project that we snapshot for every release. We just need to be careful about using
> versioning when writing the docs, unless it's a "Since WIldFly whatever" type of thing. We just want to avoid the "In WildFly x".
>
> With regards to the linking problem, I'm not sure if we (myself included) are just linking incorrectly between documents or it's just a
> limitation of Confluence. It looks like most links are done like [WFLY8:Implicit module dependencies for deployments]. I noticed some
> don't have the "WFLY${version}" prefix so maybe that's the way to go. When you use the linking function in confluence it adds the doc
> reference to the link which could be part of the problem.
>
> There are also docs that just point to old information. Like the main page references Java EE 6 getting started [1]. The Some pages are
> just dead too [2]. In some places, I tried to fix the ones I found in the WFLY10 docs, it just references the wrong version of WildFly.
> A lot of XML references too which likely point to older namespaces, maybe not a huge deal though.
>
> Overall they're not bad. They just need a little TLC. I do think too there is probably some bigger chunks we can get rid of like a lot
> of the quickstart section since we have it all on GitHub. Also subsystem references could be replaced with WildScribe.
>
> Anyway, I'm up for anything that allows the documentation to be consistent, easy to write and easy to use. The main attraction for me to
> asciidoc is being able to use git for versioning as well as being able to use variables. I don't however know how well asciidoc deals
> with multiple documents and combining them together.
>
> Regardless of the direction I'm willing to put some time into fixing/updating it. I just think before we invest any time we make a firm
> decision on the direction we want to go.
>
>
> [1]: https://docs.jboss.org/author/display/WFLY10/Documentation#Documentation-DeveloperGuides
> [2]: https://docs.jboss.org/author/display/WFLY10/Development+Guidelines+and+Recommended+Practices
>
> On Mon, Jul 25, 2016 at 9:37 AM, Brian Stansberry <brian.stansberry at redhat.com <mailto:brian.stansberry at redhat.com>> wrote:
>
> So what are we going to do about this?
>
> We’ve now reached the point where we need to start generating documentation for WildFly 11. And we’re beginning to require devs, at
> least those working for Red Hat, to write some sort of community doc as part of getting RFEs resolved. So docs infrastructure issue
> are beginning to impact our ability to get code changes in.
>
> My 2 cents: an asciidoctor and git based approach sounds good, but unless we have resources available to make it happen quickly
> basically starting from today, we need to devise a strategy based on continuing to use confluence.
>
> The biggest problem I saw in James’ original post was "Links take you to old documentation, e.g. a WFLY10 doc takes you to a page
> for WFLY8.” If that’s an inherent problem in cloning docs it’s hard to deal with. Having a living document isn’t so hard; you just
> write as if it’s a living doc and say things like “Since WildFly 10” etc. But if you can’t snapshot the living doc for a release
> without creating a lot of bad links, that’s a problem.
>
>> On May 12, 2016, at 10:32 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
>
> --
> Brian Stansberry
> Manager, Senior Principal Software Engineer
> JBoss by Red Hat
>
>
>
>
>
>
> --
> James R. Perkins
> JBoss by 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
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: OpenPGP digital signature
Url : http://lists.jboss.org/pipermail/wildfly-dev/attachments/20160725/39ce395d/attachment-0001.bin
More information about the wildfly-dev
mailing list