The APM documentation relies too heavily on current. This has created a number of issues, including bad internal and external links when pages move, or docs that cross-link to incorrect versions. As an example, the 6.3 APM Server Overview documentation links to the current versions of both the Node.js and Python agents, even though they are not compatible.
The temporary fix to this solution was to set up shared attributes in the docs repo for older versions of documentation:
shared/attributes.asciidoc:
:apm-server-ref: https://www.elastic.co/guide/en/apm/server/{branch}
:apm-server-ref-62: https://www.elastic.co/guide/en/apm/server/6.2
:apm-server-ref-64: https://www.elastic.co/guide/en/apm/server/6.4
:apm-py-ref: https://www.elastic.co/guide/en/apm/agent/python/current
:apm-py-ref-3x: https://www.elastic.co/guide/en/apm/agent/python/3.x
These attributes can then be referenced to create version specific links: {apm-py-ref-3x}/index.html will always link to version 3.x of the Python agent. While this solution works, it will become increasingly harder to maintain as our documentation grows, and every cross-document link will eventually need to be updated when a new version of each agent is released. As the agents and server continue to evolve, we need a way to correctly and easily version links between all of the relevant APM components.
I propose we move away from using current for all agent documentation, to a versioned solution. Here's what that might look like:
shared/attributes.asciidoc:
:apm-node-ref-v: https://www.elastic.co/guide/en/apm/agent/nodejs/{node-branch}
:apm-python-ref-v: https://www.elastic.co/guide/en/apm/agent/python/{python-branch}
:apm-go-ref-v: https://www.elastic.co/guide/en/apm/agent/go/{go-branch}
:apm-server-ref-v: https://www.elastic.co/guide/en/apm/server/{server-version}
index.asciidoc- branch 1.x:
:node-branch: 1.x
:server-version: 6.4
:include::{asciidoc-dir}/../../shared/attributes.asciidoc[]:
index.asciidoc- branch 2.x:
:node-branch: 2.x
:server-version: 6.5
:include::{asciidoc-dir}/../../shared/attributes.asciidoc[]:
index.asciidoc- branch master:
:node-branch: master
:server-version: 6.5
:include::{asciidoc-dir}/../../shared/attributes.asciidoc[]:
index.asciidoc- branch 6.5
:node-branch: 2.x
:python-branch: 4.x
:go-branch: 1.x
// etc.
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
index.asciidoc- branch 6.4
:node-branch: 1.x
:python-branch: 3.x
:go-branch: 0.x
// etc.
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
With the above setup, cross document links become much easier. The branch attributes will automatically ensure the correct versions are linked to.
APM Server 6.5 -> Node.js 2.x & Python 4.x
{apm-node-ref-v}/index.html
// https://www.elastic.co/guide/en/apm/agent/nodejs/2.x/index.html
{apm-python-ref-v}/index.html
// https://www.elastic.co/guide/en/apm/agent/python/4.x/index.html
If Node.js released a new 3.x agent, we'd only need to update the APM Server index.asciidoc to :node-branch: 3.x to update all links.