Notes for Giving (and Hosting) Presentations

Our office space hosts what we call "Town Halls," during which our remote employees and offices connect up to share information in a kind of giant shared Skype session without using Skype. Cameras, microphones, and connections are set up so we can not only send video of a speaker presenting company information but also the display of a connected computer.

We have enough space for projected employment numbers in our presentation space. This means we have a nice space available that was only being utilized for Town Hall meetings and company lunchtimes. Rather than let that space sit largely underutilized, we have had a few groups (and our employees) use it for after-hours technology presentations and meetups.

The setup is rather sophisticated, if I do say so myself and has largely been automated by an employee with a history of working with audio/visual equipment. For the most part, he has abstracted the complexity of the AV setup to a selection of one of a few presets on a tablet touchscreen, which can be further refined using a few interfaces on the same tablet. It's pretty slick, and he's still refining the macros controlling the interactions among the video, computer, and audio systems.

Some of the presenters for the talks have requested that events be recorded; normally the employee with AV experience is on hand for these events. That's fortunate, since he has intimate knowledge of all the plumbing that interconnects the systems and is in a very good position to improvise and fix glitches that can occur during the system's shakedown.

Recently we hosted an event where this same employee was not available onsite, and the role of recording the event fell to me, the backup systems person. On the plus side, I do enjoy learning more about recording and presenting events. It's a chance to scratch an itch for amateur video creation (I watch the how-tos from Ryan Connolly and his videocast series Film Riot and think, "That looks like it could really be fun to do...," until I look at Final Cut Pro and think, "This must be what a fighter jet looks like to an orangutan.)

Side note - If you have any desire to create sophisticated films, I strongly advise subscribing to Film Riot. Special effects and filmmaking tips broken down into easily digestible lessons, Film Riot makes me think that even I could make a half entertaining movie short. Perhaps. With the right software and decent camera...

On the other hand, it's still an incredibly complicated system that is separated by a few layers of abstraction so a monkey like myself can operate it, but if something should go wrong, I'm left scratching my head. Being kind of an anxious person, I constantly fear the breakdown of the abstraction layers, and this presentation night would have me flying largely solo.

The postscript of any event should be retrospective. What went right? What could have been done better? What was overlooked? How can I improve?

Even if things went awesomely, what can we do to make it more awesome in the future?

I'm not an AV person; my background largely comes from reading rather than doing when it comes to making videos and doing presentations. Therefore I'm a student with a lot to learn.

One good thing was that technically, this presentation went rather well. There was a glitch in the equipment where a camera wouldn't start up. While this wouldn't kill the presentation, it would have been nice to have this camera working; it was getting close to showtime, and the options were to fly without the camera and make do, or do a complete shutdown and powerup, risking that something wouldn't come back up in time (or properly) so close to the presentation start. I'm more risk averse. A less risk-averse coworker made the call to do the power cycle when I asked for input on the situation; it turned out his was the right call. It brought the camera up, and the rest of the equipment powered up as well, although the projectors gave me a bit of a fright as they wouldn't project right away to prevent damage to the lamps.

Eventually I'll need to find out if there's a way to individually power something up without having to do an automated shutdown and startup of the whole system.

There was also an issue with sound, where for some reason the notebook computer brought by the presenter refused to be heard through the headphone jack. I think it's related to his use of the HDMI output for video while the audio cable was paired with the VGA output on our system, but I need to consult with our AV designer to confirm it. Otherwise it might have been something strange with the way certain laptops deal with DRM restrictions. I'm not completely sure. The fix was simply using the notebook's regular speakers with a microphone placed over it.

I also have to remember that I need to be aware of the background. The system we have in place is optimized for presenting a town hall; that is, a speaker at a lectern, with two narrow spotlights aimed to highlight that speaker. The presentation that night had speakers that wanted to do something more of a fireside chat, out of the way of our lighting system. Our lights in the room also seemed to have a new lighting glitch that created a "disco" effect when we hit a particular preset; so we tried to get more lighting by keeping the solar and blackout shades open and allow more natural light into the space.

During the filming I realized that the camera resolution was just high enough that you can make out movement in buildings with open blinds. I'm not suggesting you could see lewd acts and the captured imagery was completely unintentional, but nonetheless all future video taken by me in our space will be done with our own shades down, regardless of lighting issues it may present.

Later on another speaker came up to present, and partway through I realized he wasn't miked. By far, my biggest fail; I should have interrupted the presenter and reminded them to put on a microphone. As a speaker, I will need to remember to check for a microphone if I wish to be recorded.

While recording the video it occurred to me that if you are presenting for a crowd outside of a comfortable circle, it may be beneficial to do a sweep of the backdrop for anything out of place or something that could be removed if it doesn't belong. The presentation was bookended by a social meetup; food and drink can easily be left out in plain sight. If your goal is to have a casual video by like-minded individuals, this may not be a problem. If you're planning on making something that may be incorporated into something larger, you may want to make sure the background and material are as vanilla as possible so the material will be more flexibly integrated.

Those were my own notes for my own reference. For a first solo performance at the tech side, I think it went fairly well. There are some things I couldn't really help (i.e., we don't have box lights, to my knowledge; I also need better knowledge of handling the transition arrangements of the two cameras and computer outputs to switch what's being sent to the recording system on the fly so there's less hesitation of what buttons to punch when, but that can only come with time. The addition of a mobile camera with transmitter would also give more flexibility in setting up shots and getting better footage, but I'm not sure it would be something we'll get budgeted anytime soon.) The items I did note...backdrop attention and insisting in the future that if you're not miked when you take the stage that you stop and get miked...are things I can improve immediately. Familiarity with the system will come with practice.

Regardless, it was an opportunity to learn more about an area with which I am unfamiliar, and I enjoyed it (once I stopped being afraid of it breaking on me!)

Stack Exchange: Moving Day

Several months ago Stack Exchange moved offices from 55 Broadway. I was with the small group charged with helping make the move; I spent part of the last day taking a few photographs and recording video on my phone.

Reviewing that footage brought a sense of bittersweet nostalgia. I took a couple of hours to assemble, render and upload a short video of the moving footage to YouTube. I readily admit it's not the finest quality in the world, but I still tear up a little when I think about it.

 

Things change as time passes on. What's interesting to me is that we live in an age when capturing small snapshots in time has become simple and mostly accessible to anyone with a phone.

Firefox: Where's My Bookmark (From the Console?)

I'm a slightly OCD type person. I'll check something several times over so the state of said thing is burned indelibly into my memory, and I can recall it later to that specific moment and not mix it up with some other similar time. For example, I'll check the refrigerator door before leaving the apartment several times to make sure it's shut, lest I worry on the subway that the fridge is acting as an apartment air conditioner.

Sometimes I end up with an irrational focus on something that shouldn't be a worry. I knew I had worked out some vacation time on the calendar, but for some reason I decided I wanted to double check it was actually entered into the private company vacation list. I needed the URL, which I had saved as a bookmark in Firefox on my OS X workstation. On my desk. Which was about 150 miles away.

That workstation didn't have graphical interface access open, but did have SSH. So how can I extract the address from the console?

I VPN'ed into the corporate network then SSH'd into the workstation. Next I navigated to the Firefox profile, located in ~/Library/Application Support/Firefox/Profiles/<something>.default.

Next I changed directories into ./bookmarkbackups. Is this automatically generated? I'm not sure. I just know there were several JSON files with dates in the filenames located in that directory.

As a quick and dirty operation, I dumped the text to my console then copy and pasted it into a text editor. The file was a list of titles, changed datestamps, URI's, etc...so a quick search within the text document for the name of the calendar turned up in the bookmark title lists. From there I copy and pasted the URI into the web browser...tada!

And that is how I pulled the address of a website from my Firefox bookmarks using the command line!

What is Documentation Done Right?

One of my new projects at work consists of revamping the checklists used when employees join and depart the company. My memory may be fuzzy...I actually have a horrible memory...but the incarnation that has been used was my own concoction from back when I joined the company nearly a year ago. For awhile, as each new person joined (or left) I would refine the action items so something overlooked the last time would hopefully not be missed the next time around.

It become something more than a checklist; it mutated into a checklist of action items with a set of how-to instructions under each entry.  We kept the final incarnation on an internal wiki system. A new person could tell that it was a dirty bit of work since the original checklist had a big old warning and link at the top telling the reader to go to another page that was updated and had more precise instructions on how to complete each step.

The finished list is one that I've been using for the past several months without much trouble. But things move on; more services are being added, the workflow for particular departments have added accounts they'd like added at hiring time, and as the company has grown the cross communication of who should be notified of what information for orientation has changed. The process has become on of the items that is a pain point, but only to the degree of an itch; people scratch it, are slightly irritated, but not irritated enough to warrant fixing the pain point...until next time, at which point the process repeats itself.

We also have a new system administrator in the team, and one of his central tenets to good systems administration practices is documentation, documentation, documentation. He's spent a good amount of time getting up to speed with our brand of Kool-Aid by revamping our internal documentation system; a side effect is reminding us of the technical debt we've created in our documentation practices. It's been a great motivator in getting my own checklist project updated. His work reminded me of something I'd lost sight of:

Your documentation isn't for you.

Adding new employees and disabling accounts had become something of my own niche. The documentation that had started out being a general list for anyone who would need to add employees became my own cheat sheet. The basics were there. But if someone new came along to do the job, the instructions didn't quite align with the exact steps needed to achieve the desired outcome. It was something I knew should be fixed but hadn't taken the time to do...until now.

To summarize a conversation Tom and I had one afternoon, "The goal should be to document and automate yourself out of the job. There's always something more to do."

My documentation wasn't really being used as documentation. It was a set of notes that I could refer to when trying to memorize the steps to reproduce a desired outcome. Gradually the steps became ingrained and the notes became more of a checklist that I would skim.

I also gradually gained a better understanding of what and why I was doing something. The documentation became burned into my head, and the notes masquerading as documentation fell into disrepair.

As I worked with the new and improved documentation I was surprised to see to what degree things were out of date. For example, our list of items to complete included provisioning a phone. We use Asterisk in-house, and each office has its own local server. Over the course of time, the newer offices had altered configurations for Asterisk, which automated more of the process and simplified the creation of accounts and phones.

I hadn't realized that at some point the New York system's documentation was out of date to the point of just being plain wrong; if someone else tried to follow those directions they would not have found anything resembling the sample entries they were supposed to follow.

I'm still in the middle of the checklist revamp. I'm trying to do it right, or at least better than before, which means it'll take some time; I'm doing an initial set of passes by literally documenting each step I take in creating new users and where appropriate I'm adding notes explaining why I'm doing what I'm doing.


Once I can follow the new instructions from start to end without a major hiccup, I'll identify points in the process where I'm missing information.  I'll look for things that are now consistent requests for modifications to accounts...such as, "Bob needs to be on <XYZ> mailing list"...and roll it into the initial setup procedure. Yes, this means having to communicate with people who manage various areas hiring new developers and salespeople.

Then I'll look for procedural refinements. For example, I've created a new badge for the user...who does it go to? Do I give it to the office manager? The new employee's manager? Do I hold on to it until the employee comes to me for it? We need to formalize this process so everyone is on the same page and knows, when asked for Bob's badge, where to look for it.

Once finished, I should have a list that is thorough enough for anyone in our technical staff to follow in creating a new employee entry with minimal mistakes.

An unfortunate side effect is how thorough it is becoming. I'm not completely through every step, and already the list and explanations is eight pages. Not the kind of checklist most people would like to deal with just to add an employee.

So what is the right way to do documentation "right?" The stuff I'm working on should be thorough enough that someone new to the job should be able to follow them, and the notes help augment an understanding of the thinking behind some of the steps. It should also pinpoint places in the procedure that need work, whether it's updating images rolled to machines or identifying where we might be able to potentially automate parts of the process. The problem is that this becomes less a checklist and more a procedural how-to, and as people become familiar with the process they start to ignore the checklist parts of the process much in the way billboards become simply visual noise I barely pay any attention to anymore when riding along the freeway.

Should documentation be adapted for more advanced users? Or should it keep some level of detail for people to refer back to, or for training newer users, despite meaning you may have to maintain various levels of documentation and keep them in parity?