Category: Documentation

Sheldon Hull explains the value of asciidocs:

Documentation is such an important part of a developer’s life. I think we often take it for granted, and it’s an afterthought in many projects. However, as I consider my work, I know that I’m not reinventing the wheel very often 😀. Most of what I do is built on the back of others’ work. When I use tooling, I’m reading the documentation and using it as my basis to get work done. When I use my notes and blog posts as a reference, I’m using my informal version of knowledge gathering.

INVEST in documenting your work as you go, for the person behind you. You don’t find time to do it, you make time to do it while you work, as a first class citizen of your work, not an after-thought. Think of all the times you’ve had to dig for answers and save someone else that experience.

Sheldon is not wrong.

Dave Mason wants to document each SQL Agent job, including maintenance plans:

I’m not a regular user of Maintenance Plans for SQL Server, but I run into them from time to time. I had a task to document all of the SQL Agent jobs, which for a number of environments, included some Maintenance Plans. This became a more time consuming task than I had anticipated!

I had known beforehand that Maintenance Plans were SSIS packages under the covers. So I started with a query on msdb.dbo.sysssispackages. I also knew that SSIS packages are essentially XML data. 

Take advantage of the bulk of time Dave had to sink into this.

Ben Slater has a great post on service level agreements:

It should set the customer’s expectations, be realistic and be crystal clear, with no scope for misinterpretation. Well, that’s how they are meant be. But unfortunately, in the quest for more sales, some MSPs tend to commit themselves to unrealistic SLAs. It’s tempting to buy into a service when an MSP offers you 100% availability. It is even more tempting when you see a compensation clause that gives you confidence in going ahead with that MSP. But hold on! Have you checked out the exclusion clauses? Have you checked out your responsibilities in order to get what you are entitled to in the SLA? Just as it is the MSP’s responsibility to define a crystal-clear SLA, it is the customer’s responsibility to thoroughly understand the SLA and be aware of every clause in it. That is how you will notice the shades of gray!

We have put together a list of things to look for in an SLA so that customers are aware of the nuances involved and avoid unpleasant surprises after signing on.

This is important to know when you’re using a managed service but it also works internally: as a developer or manager on a product that people (presumably) rely upon, how you deal with outages and issues matters a lot.