[wildfly-dev] One Doc to Rule Them All

[Brian Stansberry]

Practical tip:

tl;dr;

Don’t include the Confluence space prefix in the markup for cross document links.

Long version:

An issue with using a "live / always up to date doc” is I expect we’ll want to snapshot it when we do releases, at least for majors. The way confluence creates links between pages can work against that though.

But this can be mitigated with careful work.

Say I want to create a link in the “Admin Guide” page to the “RBAC” page. The little “link” icon at the top left of the editor helps me do that. The problem is it creates markup like this:

[WFLY:RBAC]

That link will be a problem when we create a snapshot of the docs for WildFly 11 since in the snapshot it will still say “WFLY” and the effective URL wll be 

https://docs.jboss.org/author/display/WFLY/ <https://docs.jboss.org/author/display/WFLY/>RBAC

and not the WFLY11 snapshot URL:

https://docs.jboss.org/author/display/WFLY11/ <https://docs.jboss.org/author/display/WFLY11/>RBAC

Anyone following the link will get directed to the then current docs, which may have inaccurate information for WildFly 11. (Right now our docs have the opposite problem that James mentioned on this thread; the WFLY10 docs are a copy of WFLY9 which was a copy of WFLY8 and when those copies were created a bunch of links pointing to [WFLY9:xxx} or even earlier were created.)

Avoiding this problem just takes a bit of care though. If you use the link button, edit the resulting link test to remove the “WFLY:" space prefix, resulting in

[RBAC]

With that syntax the link becomes relative to the current document’s space, and when that space is copied the copies will also have relative links.

> On Jul 29, 2016, at 2:54 PM, Jason Greene <jason.greene at redhat.com> wrote:
> 
> I think we should stick with what we have, which works well enough, and just have a live / always up to date doc.
> 
> Everyone is pretty busy at the moment, so to switch to any new option, the starting point would be a volunteer willing to own all of the porting and reformatting work on all of our existing content. 
> 
> 
>> 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 <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
> 
> --
> Jason T. Greene
> WildFly Lead / JBoss EAP Platform Architect
> JBoss, a division of Red Hat
> 
> _______________________________________________
> wildfly-dev mailing list
> 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



-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/wildfly-dev/attachments/20160729/fd9992ab/attachment.html