permalinks in documentation

[inqueue]

There are instances where linking to "current" documentation is a bad idea. For example,

http://elasticsearch-users.115913.n3.nabble.com/What-is-the-meaning-of-throttle-time-in-millis-tp4050893p4050921.html

The post points to the link for current documentation which contains no info for store throttling, like the 1.7 version of the document.

Is there a way we can encourage the use of permalinks in our documentation to avoid this problem? Sometimes it is not obvious how to obtain the permalink in Elastic documentation; Logstash Introduction is an example.

New documentation is comes with every release and we should try to encourage those linking to the docs to only use permalinks as those links run the risk of being invalidated.

[dedemorton]

Links to the documentation should almost always use the versioned link rather than current.

[inqueue]

Documentation is ever changing. There are often broken links found in GH issues, Discuss posts and other places where current link was pasted. Sometimes even the versioned link changes, but this is less often. And getting the versioned link is cumbersome. Can the documentation please include a permalink that will NEVER change?

[dedemorton]

@inqueue I'm curious if there are specific content areas where you're seeing a lot of churn that's causing you pain. I'm not sure about the permalink question (I'll leave that to @nik9000 to answer because I think our doc tools are a huge limitation here). However, writers should be setting up redirects to minimize broken links. If you are seeing a lot of broken links, that's a bug, and we need to fix it.

[nik9000]

I think we should stop using current which would go a long way for this.

I think it is super reasonable to expect that a versioned link won't change, except for master and the .x links. Those are "development" branches are constantly being hacked. For the most part I think we should get permanent links by being disciplined about not moving things or leaving redirects when we do. Some tools might help here, but those are a little ways off.

[dedemorton]

I think it is super reasonable to expect that a versioned link won't change, except for master and the .x links.

I agree, but I think some writers choose to backport these types of changes because it makes other backports easier and it makes the version switching work better. If you don't backport the changes, you get into a weird situation where switching versions drops you into an entirely different "book". (Hopefully our site redesign will improve this situation by making the content easier to navigate from a single pane, but right now, the user experience is sub-optimal.) I'm playing devil's advocate here because my preference is to NOT backport structural changes.

TBH, I am not a big fan of moving content between books/repos. Besides breaking everyone's bookmarks/links and making it harder for experienced users to find content, it essentially erases the original author's attribution in GitHub. (No one is going to run git log to see the full history.) I feel like we've done that too much, and our users (including support) are getting whiplash.