Home Dashboard Directory Help
Search

[BOL] Make Books Online examples easier to get to by Jamie Thomson


Status: 

Closed
 as Fixed Help for as Fixed


28
4
Sign in
to vote
Type: Suggestion
ID: 487416
Opened: 9/1/2009 3:55:28 PM
Access Restriction: Public
0
Workaround(s)
view

Description

Its true to say that the most used parts of BOL are the examples and hence it seems daft to have them stuck down at the bottom of the page where they are most difficult to get to.

This creates lots of unnecassary mouse scrolling - think of all the carpal tunnel syndrome cases you could solve in DBAs if this weren't the case.
Details
Sign in to post a comment.
Posted by Microsoft on 7/5/2011 at 5:53 PM
Hi Jamie,
I'm resolving this as fixed. I've updated our T-SQL Reference template that writers use when creating new or updated T-SQL topics. In that template I include a requirement to add a link to the Examples section in the Introduction section if the topic is too lengthy. While we won't retrofit all topics immediately, this work will be done over time.

FWIW, users can easily get to examples by simply clicking the Collapse All button at the top of the topic. But, I guess it's difficult for users to notice that button.

Best,
Gail Erickson
SQL Server Documentation Team
Posted by pattmania on 9/4/2009 at 3:19 AM
I liked the proposed format. I think that the examples link could do with being slightly more prominent though - especially for users who aren't used to the documentation format, who could otherwise face a wall of technical explanation without it being obvious where the funtional examples are.

I disagree with the point that the examples should at the bottom in an attempt to make the person read the whole article. I appreciate that there is valuable information in the more detailed explanations and have learnt a lot from them myself where appropraite, but I think it is the responsibility of the developer to understand the consequences of what they are delivering and the context of their situation should determine whether or not it is appropriate to go for a detailed explanation. I also personally find that understanding the syntax first (within examples) and then the detail around it is a more effective way to learn as the context of the detail is more likely to be understood.
Posted by Jamie Thomson on 9/3/2009 at 2:18 PM
Hello,
I have received an invite to check out http://msdn.microsoft.com/en-us/library/ms174335.aspx. Here is my feedback.

At first I didn't like the fact that the examples were on a different page but then I noticed your comment to me saying "In this particular case, it goes to a separate topic that contains only examples, but the link could also just be an internal bookmark link to the bottom of the reference topic itself". I'm glad about that - I would prefer everything in one place with a link at the top to the section down below.

As for the examples themselves - I like the fact that you have a summary section with links to the individual examples. I'm very much in favour of this new format.

If you need any other feedback just let me know.

-Jamie
Posted by Microsoft on 9/3/2009 at 12:59 PM
Hi,
We have actually being discussing this issue within out Database Engine UE team. We have a prototype topic that I would like you to look at and respond to in this bug. The topic is available here: http://msdn.microsoft.com/en-us/library/ms174335.aspx.

The prototype is the INSERT topic. Note that there is a link to the Examples at the top of the topic. In this particular case, it goes to a separate topic that contains only examples, but the link could also just be an internal bookmark link to the bottom of the reference topic itself.
Posted by BI Monkey on 9/2/2009 at 4:26 PM
A bit off topic but if the page designs allowed for us with too-high resolution screens / fading eyesight to increase the text size and keep the text still on the page would be nice!
Posted by ACollins74 on 9/2/2009 at 5:42 AM
Navigational links would be nice. Sometimes, i find the wheel on my mouse difficult to turn after a long day of T-SQLing.
Posted by David M Maxwell on 9/2/2009 at 4:05 AM
I would disagree with this, completely. There are often a lot of 'gotchas' in the more detailed explanation that you're going to miss if you skip right to the examples. "People are going to do it anyway" is not a reason to make it any easier. I've learned from first, and second hand experience that the content of the BOL entry is far more valuable than the examples. Let's keep the examples where they are.
Posted by Seth Lynch on 9/2/2009 at 1:11 AM
Although this is a bit jokey it is also true. I always scroll down to the examples and then if I have the time and inclination I read the rest of the page. Put them at the top and add more!
Sign in to post a workaround.