Need a strategy for linking from the product to the documenation

[dedemorton]

Right now, we are hard coding links in the product that point to the documentation, and those links are likely to get out of date quickly (especially for newer projects where the doc is likely to undergo a lot of restructuring).

I've created the following document as a place to discuss issues and come up with ideas for implementing a doc linking strategy. I'd appreciate feedback and ideas and some input from developers about how we can best implement a workable strategy. Please feel free to add comments or edit the document directly. I just wanted to get the conversation started; I don't have all the answers.

https://docs.google.com/document/d/1r0-DooTSbZS0kAdYhjd-XIy7naPFBIWL-SyXNqRfBs4/edit#

@debadair @palecur Can you take a look and add your comments? Then we should tag some people in development on this question.

[dedemorton]

The Kibana team has implemented a strategy to create dynamic links. Here is the PR: elastic/kibana#6989

@clintongormley Can you close this issue when the code you've written for validating the links is in place? Not sure where you are at with that....

[clintongormley]

@dedemorton I've written the code, but I'm waiting for @Bargs to merge that feature branch into master so I can test it out.

[Bargs]

If all goes according to plan it should get merged sometime before alpha4.

[dedemorton]

@clintongormley Just wanted to confirm that your link checker has been merged so I can close this issue (looks like PR for generating dynamic links has been merged: elastic/kibana#6989).

[clintongormley]

@dedemorton that was merged into a feature branch, not into master. I'm still waiting for @Bargs to tell me when the feature branch is merged into master

[Bargs]

Our dynamic doc links directive got merged into master along with the CSV upload UI.

[clintongormley]

Just to let you know, I tried merging the Kibana links checker and currently it fails: the reason is that Kibana has a 5.0 branch and Beats doesn't yet. The master branch checks are just fine.

@tsg when is Beats planning on cutting a 5.0 branch? I know Elasticsearch are planning on doing this as soon as alpha5 IRC is released. If beats were to do the same, then Kibana's doc-links would work for alpha5.

[tsg]

We can do the same, yes. Just to make sure, we'll need a branch named '5.0', right?

[clintongormley]

Correct. We're going to branch as follows:

• 5.0 -> v5.0.0-beta1
• 5.x -> v5.1.0
• master -> v6.0.0