Tsql Tuesday #171 The most recent issue you closed

It’s #TSQL2sday!!

T-SQL Tuesday is the brainchild of Adam Machanic (Blog | Twitter). December 2009 was the first T-SQL Tuesday invitation that went out by Adam. It is a monthly blog party on the second Tuesday of each month. Currently, Steve Jones (Blog | Twitter) organises the event and maintains a website with all previous posts which you can find here. Everyone is welcome to participate in this monthly blog post.

The Ask

This month’s T-SQL Tuesday is hosted by Brent Ozar (Blog | BlueSky). Brent invites us to "write a blog post about the last ticket you closed".

The call raised

I was recently asked to help someone out with a problem they were having with a process that was failing. The call was raised for me to provide some insight into why the failure was occuring and offer advice on how to resolve it. I am a consultant and my time is often spent with teams that are picking up new tools and techniques and so I am often asked to provide guidance when things go wrong.

After a bit of digging, my response to the ticket was that this was expected behaviour, because of x and that if they did y, then the process would work as expected. I also supplied a link to the specific part of the documentation that explained why this was the case. Issue closed.

Somebody once said read the docs

I can’t remember the first time this message really caught my attention, I remember reading an article of some sort that explained the real benefits in reading the docs. I am convinced it was Brent, but my google-fu is off. It maybe was this tweet…

…but it feels way too recent, but it’s a very concise version of that message!

Reading the documentation is a key part of understanding how a system works, how to use it effectively and how to troubleshoot it when things go wrong and it amazes me how often I find myself providing insight to others simply because I read the docs!

Why you should read the docs

Some of the benefits that I have come to appreciate are…

Improve your understanding

• Documentation provides an overview of a system, including its architecture, functionalities, and intended use cases.
• You can be guided by best practices, helping you to write more efficient, secure, and maintainable code.
• You can discover features and capabilities of the system that you might not have known about.
• You can stay current with the latest enhancements, whether that is new features, updates, or deprecated functionality.

This deep understanding allows you to use a system more effectively and creatively, maximising the value you get from it.

Improve your troubleshooting skills

• Instead of waiting for answers from others, you can often find solutions and explanations directly in the docs.
• Documentation usually includes troubleshooting sections, offering solutions to common problems and errors.

Knowing how to navigate these sections can help you become more self-reliant in solving problems and reduce downtime when issues arise.

Improve your worth

• Knowing you have the resources to understand and solve problems independently can boost your confidence in your own skills and decision-making abilities.
• You also become more valuable to your team and organisation, as you can provide guidance and support to others who might not be as familiar with a system.

You would be amazed at how quickly your reputation can grow when you are seen as a go-to person for help and advice and all because you, dear reader, chose to read the docs.

Why you should re-read the docs

I have come to realise over time that I also seem to mis-remember things! We aren’t great at remembering lots of things and we are often guilty of making assumptions. The data landscape is vast and continues to grow. It’s really hard to remember all the things. I might not touch a piece of SQL for months, and so my memory of specific functions or behaviours may become vague over time. I will regularly review content that I have read before or that I think I know. I find that I can sometimes pick up on things that I have missed or that I have simply forgotten about.

#RTFM

While reading documentation might require an initial investment of time and effort, the long-term benefits it brings in terms of knowledge, efficiency, and empowerment are well worth it.