Improve visibility of features by version

[binki]

Is your feature request related to a problem? Please describe. When browsing SQL Server features which were newly introduced in recent versions, I want to be able to quickly see which version of SQL Server introduced a particular concept, topic, or subfeature.

When I try to figure out which version of SQL Server has a particular feature, I am told that I am supposed to use the version selector for this. However, the version selector doesn’t always reliably know about all of the various versions—particularly versions which aren’t in the version selector or when features are subfeatures.

Describe the solution you'd like I’d like to be able to see quick compatibility tables like MDN’s ones for recent web features.

Additionally, if the version selector could show you on screen prior to clicking on the version entry that the version is not supported by the current page/feature to avoid the redirect to the latest version, that would be helpful.

Additionally, if, when selecting an older version than supported, the version selector could redirect to the oldest supported version rather than the newest supported version of the documentation, that would at least tell the user something useful rather than getting them further away from the information they are seeking.

Describe alternatives you've considered

Additional context https://github.com/MicrosoftDocs/sql-docs/issues/2918 https://github.com/MicrosoftDocs/sql-docs/issues/3823

I was asked to file a feature request here.

[brettshearer]

I concur. Trying to guess versions creates a large amount of work when trying to either: a/ force minimum version in your product b/ cater for older versions and then having to check in your code around every single call to the method

Even function changes such as allowing max(uniqueidentifier) are critical to understand because developers have the latest version, they try something, it works. Let's ship!

[KevinPence]

+1 to this request. The Version Selector lets you choose a version of the doc to see, which is not the same as listing supported versions of SQL Server for a given feature.

I think it's a mistake to try to do both jobs via the Version Selector list. It adds extra steps for the user, obscures basic information about the subject of the article, and still requires the docs team to maintain version info somewhere.

Lots of pages used to use the Applies to: header to display the version for which a feature was first released. To me, this is the most straightforward way to provide the information.

I don't understand why @MightyPen scrubbed these useful annotations last year without a reliable alternative in place.

@MikeRayMSFT briefly added them back earlier this year before scrubbing them again the same day.

What gives?! Is this an evil Microsoft plot to sell SQL Server upgrades by harassing developers? We don't sign the checks! OK, I don't really think it's an evil plot, but this is a real source of frustration. Can someone please explain what's going on?

[MightyPen]

@MikeRayMSFT @rothja @craigg-msft All, Here in this Docs-level Issue in GitHub, a few customers explain how their needs are not always well met by the set of version-related informations offered by repo 'sql-docs-pr' on Docs:

• AppliesTo
• OPS Versioning

(What's New is not mentioned.)

---

@binki This Issue 2342 here is fine. FWIWorth, it is somewhat better when SQL Issues are generated by clicking the Feedback button at the bottom of a SQL article on Docs.m.c.

Thanks for submitting this feedback. It happens to have a timely arrival :-)

@KevinPence The version-specific detail in some of the AppliesTo values was removed because it was often incorrect for PARTS of the article, and made worse depending on the Version selector value. About all the removed version detail could legitimately say is something like - "This main subject of this article was introduced into the SQL Server product starting in version 2008" - too long to clarify in the AppliesTo value. The article's introduction is perfectly allowed to say something like the sentence.

And yes, the Versioning selector would be better if its list excluding Product+Version entries which do not apply to the current article. Adding this behavior to the Versioning selector is under discussion, and it must complete for Dev resources with many other tooling efforts to get scheduled. Even then, we have talked about alternative ways of displaying this info. When we examine all the scenarios and their details, it is not a simple task. But we understand why you all are asking for enhancements to the current situation.

Thanks.

---

(https://github.com/MicrosoftDocs/feedback/issues/2342)

Thanks. G

[brettshearer]

It gets even more complex when SQL 2014 document is no longer available (or never was?). Take MAX(uniqueidentifier) as an example. This was added at some stage, but without SQL 2014 docs, I cannot tell exactly when. I actually got caught by this one; developers had a newer version of SQL than minimum, and started using this functionality.

This could easily be annotated in the help alongside the argument, rather than having to wade through old versions of documents. See any published research papers with citations as an easy way to do this.

-- Aggregation Function Syntax
MAX( [ ALL | DISTINCT ] expression )
... expression Is a constant, column name, or function, and any combination of arithmetic, bitwise, and string operators. MAX can be used with numeric, character [1], uniqueidentifier [2], and datetime [1] columns, but not with bit columns. Aggregate functions and subqueries are not permitted.

[1] = SQL 2000 [2] = SQL 20012 SP 1 CU2

[MightyPen]

@binki , @brettshearer , @KevinPence , @rothja , @MikeRayMSFT

The online website https://Docs.microsoft.com/sql/ does not contain SQL Server 2014 Transact-SQL articles. SQL 2014 customers would use the 2016 T-SQL articles, as a good but imperfect substitute.

However, you can obtain the SQL Server 2014 'Transact-SQL' documentation articles, by using SSMS.exe (SQL Server Management Studio, version 18.0+).

As the attached screenshot shows, SSMS.exe Help menu can launch the Help Viewer tool (must be version 2.3+).

 

. .

[KevinPence]

Thank you for patiently explaining your team's reasoning, and I'm sorry for blowing off steam in your direction. I understand that this is a difficult and ongoing challenge. I also appreciate the suggestions provided. Is it possible to import the docs from SS2008 and SS2012 into SSMS help viewer? I know the docs for these versions don't have the same organizational structure as the currently supported docs

I've noticed in the past couple of weeks a few areas of the tSQL Reference that either take for granted or directly instruct users in the old usage of "Applies To". Most notably, is the documentation's syntax guide: https://docs.microsoft.com/en-us/sql/t-sql/language-elements/transact-sql-syntax-conventions-transact-sql?view=sql-server-ver15#applies-to-references

I think discrepancies like this in the way AppliesTo is used and discussed within the tSQL Ref have contributed to my confusion and frustration. I'd like to help weed out these discrepancies as I use the Ref, but unfortunately, I don't have time to submit PRs. What would be the best way to flag articles for review? Can it be done without having to create a new ticket and re-explain the issue each time?

[MikeRayMSFT]

@KevinPence - thanks for being very specific, and taking time to look at file history. The reason some of the applies to version information was inserted, and then removed was because it wasn't accurate enough. In some cases it was just incorrect.

I really appreciate everyone's comments and I'm working with my team to help clarify versioning.

[MikeRayMSFT]

Created internal tracking item: User Story 1709946: SQL | Improve visibility of features by version

[CarlRabeler]

@KevinPence Is it possible to import the docs from SS2008 and SS2012 into SSMS help viewer? Yes - we are updating the content this week to show how to install older versions of SQL help docs into the current version of SSMS - we have tested, 2012, 2014, and 2016. Carl

[CarlRabeler]

https://docs.microsoft.com/en-us/sql/sql-server/sql-server-offline-documentation?view=sql-server-ver15#sql-server-2014-offline-content

[CarlRabeler]

please-close