JIRA and Confluence documentation links broken

[Bob Swift OSS (Bob Swift Atlassian Apps)]

Has anyone had problems with links to the newer documentation? All the pages seem to have id numbers in the url and these change. There doesn't seem to be a way to link to version specific pages by name. Are these kind of links persistent? For instance will https://confluence.atlassian.com/doc/links-776656293.html continue to work for next version of Confluence? 

Here is a top 3 google search link that is broken: https://confluence.atlassian.com/jiracloud/linking-issues-735936953.html. I have no idea how to find the equivalent page that is current. This leads me to believe that many similar links will break as soon as another release ships etc.... 

Another example is https://confluence.atlassian.com/jiracore/jira-core-7-1-x-release-notes-802161668.html. No one can guess what the 7-2 link will be. Same for https://confluence.atlassian.com/jiracoreserver071/jira-core-overview-802172330.html. Is there a latest url?

It is common in documentation to link to Atlassian documentation including release notes or specific topic areas and this seems to be difficult or impossible without the links breaking. More over, in the past when a link did get broken because of a change in the latest version of the documentation, it usually brought up a renamed page dialog or similar that allowed people to continue on to the correct page. Now all you get is a page not found.

Any insight on how one should deal with this would be appreciated.

[Rachel Robins]

Hi Bob,  

Thanks for raising this, and I'm so sorry for the frustration our docs are causing.  As you know, I’m a tech writer for the Confluence team, so please forgive me if I don’t have answers to all your questions about the specifics of the JIRA docs.    

I’ve resolved the problem with the broken links to the JIRA Cloud space, which is now divided into three spaces, as explained on this page The JIRA Cloud documentation has moved. It was a mistake our end, and I’ll make sure the team understands how it happened so we can do better in future.  

As for the current difficulties you’re having getting to the ‘latest’ JIRA docs, especially release notes, in a consistent, non-changing location, I’ve passed your concerns on to the JIRA Writers, so expect to hear something from them soon.  

I’ll also pass on everyone’s concerns about our custom Scroll Viewport theme not showing the last updated date of docs, and the format of the URLs and see if we can improve this experience for everyone. 

[Steven F Behnke]

Thank you for taking some time to answer this. I realize we're discussing Atlassian documentation as a whole when in fact you're operating in a specific subset of that system.

To be honest I think the change is the most frustrating part. Many of us in the ecosystem had become accustomed to specific patterns and those patterns are now gone entirely. It was wonderful being able to rely on confluence.atlassian.com/display/PRODUCT to get me to the latest documentation for that product all the time. We use the concept of Copy Space for documentation ourselves so again that was reliable.

Thanks for considering the feedback.

[Bob Swift OSS (Bob Swift Atlassian Apps)]

Thanks here as well. Please keep up the communications on this topic.

[Rachel Robins]

Oh and I realised I missed one part of your question Bob.   We have no plans to change the structure of the Confluence docs at the moment.

http://confluence.atlassian.com/display/doc will remain the Confluence Server (and Data Center) latest space, which we'll update after each release. The release notes will remain in this space also.

http://confluence.atlassian.com/display/confcloud will remain the Confluence Cloud documentation space, and will be updated every time something changes in Cloud.   

If you're concerned about page ID changes and linking to our pages now that we have Scroll Viewport enabled on these spaces, you can continue to use the standard Confluence URL if you prefer (for example if you're linking from your add-on's docs to ours, use links like http://confluence.atlassian.com/display/doc/files which will get redirected to the corresponding viewport URL automatically like this https://confluence.atlassian.com/doc/files-139465.html)

[Steven F Behnke]

I really hate what they've done with their documentation. It's no longer predictable and it longer has much rhyme or reason. I don't care for what they've done with the Scroll Viewport add-on if it resulted in their documentation quality dropping.

I also find tons and tons of broken or wrong images and broken links.

[Bob Swift OSS (Bob Swift Atlassian Apps)]

Is it just me or does it seem that there is a lot less documentation than there use to be? On the JIRA side it seems to be split up into separate areas and it is a hard to get the big picture (across areas).

[Bill Bailey]

And JIRA is in better shape than Confluence. I have often come across similar pages in two different trees. Not sure what is up with that. And I know that some of the docs haven't been updated in years (can't see the date anymore with the Viewport added).

But the link thing is perplexing. It seems to defeat some of the advantage of using Confluence for documentation to append some unpredictable number at the end.

[Steven F Behnke]

@Bob Swift [Bob Swift Atlassian Add-ons], there are definitely pages in the JIRA sections that only exist in the 6.4 "archived" documentation. Not sure what to make of that either.

[Alex Yasurek]

Those numbers are added by the theme plugin they are using which is Scroll Viewport. I know that for some of these links if you remove the ending numbers and .html, the link still works.

For example, the two links below both work and lead to the same page:

https://confluence.atlassian.com/jiracoreserver071/jira-core-overview-802172330.html

https://confluence.atlassian.com/jiracoreserver071/jira-core-overview

Problem is that this doesn't hold true for all links. If I do the same to the release notes link, it doesn't work:

https://confluence.atlassian.com/jiracore/jira-core-7-1-x-release-notes-802161668.html

https://confluence.atlassian.com/jiracore/jira-core-7-1-x-release-notes

I am not sure what the difference is but I do know what is adding all those extra numbers is the Viewport plugin because we use it also and it does the same on our instance.

[Bob Swift OSS (Bob Swift Atlassian Apps)]

That was a helpful trick . Strange how it doesn't work for release. 

[Betsy Walker {Appfire}]

I don't see where the JIRA doc writers chimed in. This is totally frustrating, especially for Marketplace vendors who want to provide a link to Atlassian documentation in order to succinctly describe a 'core' concept. We need a "latest" means of accessing JIRA content as well.

[Stefan Ernst]

There are several things that puzzle me about this approach regarding Atlassian online documentation but the most important one is:

If it is such a must have feature to theme and style Confluence then why rely on 3rd party plugins instead of implementing those features in Confluence themselves? This way it looks like Atlassian is not confident enough to use their own unaltered standard product.

Another aspect is how it is implemented. I dont think the release hub and the succeeding JIRA release documentation is really optimal. It was a departure from the previous linear release notes and it left me using google to access the various version specific release notes.

It could have been handled better, at least with a overview page that lets you access all resources from a single entry point. Right now I cant find that, instead in most cases, google leads you somewhere into the old 6.4 documentation from where you cant easily access anything relating 7.x+