Preparing for the Road Ahead: Documenting Your Casper Suite Setup

Watch this JNUC session in its entirety.

Have you ever started a new job without a clue where to actually start? Not everyone writes a “If I Get Hit by a Bus” document before leaving their position, which makes it awfully difficult for someone to step into their shoes. Today’s JNUC session presenter, Rich Trouton, recognizes this less-than-ideal circumstance, and discussed how to prevent it from happening in your workplace by providing proper documentation. It can be a largely manual process – yes. So it begs the question: Why document?

Trouton offered a convincing answer. “One reason for me is that I like to take vacations,” he said smiling. Trouton then showed a photo of the ocean. It was his beautiful, thousands-of-miles-from-anywhere view. “My internet connection was both slow and expensive, which focused my priorities toward using my expensive internet time to post photos to Facebook and away from checking my work email.”

But how was he able to easily disconnect from work? Easy. He left behind documentation that covered what to do in case of emergencies, along with outlining his day-to-day tasks.

Trouton recalled an instance where he was on his way to the airport when he got a call from someone at work. They had a power outage at their main data center and didn’t know what to do. He asked, “Can you find the Mac server rack?” They did. “Do you see the packet marked ‘Emergency Server Startup and Shutdown Procedures’?” They did. “OK. Open that and start reading.” He talked with his colleagure for a few minutes and hung up.

“Without that packet, I might have been trying to walk someone through the shutdown procedure for about 15 servers and 12 RAID arrays,” he said. “That is why I document.”

But when should you document? Trouton suggested keeping the appropriate documentation:

Required Documentation
Documentation of certain processes and procedures may be required by law, or a policy, at your workplace. And if it’s not required, don’t forget about disaster recovery documentation. It’s often the most important form of documentation.

Business Continuity
All-in-all, make sure you have documentation so others can accomplish the work if you’re not around. “Even if you get hit by the lottery bus, the job still needs to get done,” Trouton said.

Common Tasks
While someone may not need to know how to print from the office printer, they may need documentation around setting up the printer to print double-sided from the legal-sized tray.

Unusual Situations
Some tasks are simple. But would everyone know how to troubleshoot a new MacBook Pro that isn’t booting up? Document that they should use the non-default NetBoot set you built to support new laptops.

When documenting, Trouton explained, keep the audiences in mind. These often consist of you, your colleagues and everyone else.

“The documentation that you write for your own use is first and foremost a memory aid,” Trouton said. “This kind of documentation can take all kinds of forms, from notes typed into a notebook app, emails sent to yourself or information posted to a wiki.”

When colleagues are the audience, use documentation as a method to teach them to solve issues. “If you can teach them how to fish, maybe they can start catching fish on their own. Even better, maybe they’ll be able to start arriving at better solutions,” Trouton said.

And if anyone is the audience, set aside what you think they may already know. Help the reader discover if the problem you’ve outlined in your documentation applies to them. If yes, provide step-by-step directions to fix the problem.

“Another important part of my documentation method is what I call ‘genericizing.’ This is the fine art of removing as much specific identifying information from your document as possible, while hopefully still making it clear what you mean,” Trouton said.

The art of documentation is a bit different for everyone. Whether it’s creating calculated screen shots or simply taking copious notes, it’s important to do what works best for you. Consider a text editor, graphics editor and/or a video editor. Each one can help document in different ways. And don’t forget to keep it in one place (perhaps one folder), so it doesn’t get lost.

Lastly, post your documentation. Whether it’s on a Confluence wiki or a SharePoint site, make it available to those who need it.

Trouton ended the session by walking through how to document Casper Suite (know called Jamf Pro) setup. Trouton recommended concentrating on: Client Management, JSS Management, Policy Management and Software Management.

Keeping everything in mind, Trouton said, “Documentation does not need to be long in order to be effective. In the case of the documentation for uninstalling the Casper agent, I’ve linked back to Jamf’s documentation on it, as well as providing the necessary command in the documentation.” He also gave some great resources to help users query Casper Suite via the API.

Trouton ended saying, “Getting into the habit of documentation has helped me immensely in many ways and being able to help others through what I’ve documented has been rewarding, both professionally and personally.”