4:23 p.m.
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(a)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(a)redhat.com
<mailto:jperkins@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(a)lists.jboss.org <mailto:wildfly-dev@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(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/wildfly-dev
--
Brian Stansberry
Manager, Senior Principal Software Engineer
JBoss by Red Hat