How To Run A Useful Meeting

I’m on a manager’s schedule, not a maker’s schedule, so I go to, and run, a lot of meetings, and I’ve made a few rules for myself that make meetings more useful.

No Agenda, No Meeting

Meetings without agendas are likely to go nowhere and do nothing. Even recurring meetings need agendas. The agenda should be a few lines covering the specific reason(s) for the meeting, and this agenda should be emailed to the people who will be at the meeting at least 24 hours before the meeting. The reason for emailing the agenda, rather than only putting the meeting agenda in the invitation, is that people will often reply to the emailed agenda addressing the very questions you wanted to answer in the meeting. Sometimes, you’ll address all the reasons for having that meeting via email and you don’t need to have the meeting – which is always a good outcome. Emailed agendas are like the pre-interview phone screen – if the agenda can’t get past this step, no need to waste everyone’s time in person.

An agenda also serves to focus the meeting as it progresses, helping people keep the meeting on track.

Always Take Notes

You, as the organizer, should take detailed notes (except for the times when you are at the whiteboard, or other such situation). You set up the meeting, you have to take the notes. It was important enough for you to break up every attendee’s day, and to cost the company the combined salary of the people you invited, so you should make sure you record what happened in the meeting. Good notes contain:

  • A list of attendees
  • A copy of the agenda
  • Short summaries of discussions/disagreements
  • A list of what was decided, including who will do what

You don’t need to worry about grammar and spelling as you take the notes – you can clean them up later. What you do need to do is email all the attendees the notes (some of my friends check the notes into revision control as well; this is a good practice that I need to adopt). When you email out the notes you’re giving people time to correct your notes and clarify what everyone meant.

If you whiteboarded something during the meeting, take a picture of it and include the picture in the email.

Also, if you have trouble paying attention in meetings (like I do), volunteering to take notes is a great way to stay focused on the meeting.

Let People Leave The Meeting

If someone doesn’t need to be there for the whole meeting, don’t make them stay. Let them go after they’ve contributed their part.

Meetings Happen In Person….

Or do they? Scrums and other short status meetings are good candidates for meeting over IRC. A friend of mine who runs a lot of distributed groups runs many of his shorter (and longer) meetings this way, with the help of a few tricks like an IRC bot that can be told when the meeting has started and stopped: after the stop command is received the bot will make a web page from the meeting notes. Scrums are particularly amenable to this format because people can post their prepared list of updates into the chat window for all to see and comment on. Another advantage of scrums or status reporting meetings over IRC is that people don’t have to leave their desks (this seems obvious, but making meetings like scrums fit into people’s workflows is important). Meetings over IRC also let people observe a meeting by lurking in the chat room, which is something that is harder to do in person.

IRC can be a useful tool for in-person meetings as well, providing a place to paste texts, share links, record notes, and so on. I think that Google Wave (or something like SubEthaEdit) has potential for this purpose as well, but haven’t tried it.

What Works For You?

What techniques do you use to maximize the value of your meetings? I’d love to hear about your experiences in the comments.

July 18, 2010 communications, management

Recent Readings

On MicroSD Problems – The investigation of a failing batch of MicroSD cards leads to an amazing story of detective work that delves in to the world of semiconductor manufacturing, gray markets, and failure rates.

CloudClimate CDN Speed Test – A clever use of XMLHTTPRequest to time HTTP downloads of small files (64KB) to your machine from the leading CDNs and cloud providers. I’m a sucker for the pretty graphs the tool creates with the data, but beyond that I can see how this tool is useful for people evaluating CDN/cloud choices by geographic location.

Drizzle – “An Open Source Microkernel DBMS for High Performance Scale-Out Applications” are all words I know and put together in that order sound interesting. Has anyone played with this yet?

NCSA Mosaic – Now you can run Mosaic on your hexacore i7 box; the fastest AJAX is the kind that doesn’t even happen!

The Panic Status Board – I recently learned the term “information radiator” and this is a perfect example of the concept. A simple, striking visualization for what is most important to Panic for the operation of their business. It’s a network operations center for your entire business. It’s hard to see how a single board would work for a large organization, but I’d love to build one for the group I’m in at work.

DevOps, SecOps, DBAOps, NetOps – A discussion of the problem of silos inside operations organizations, and how it is important to focus on the relationships between those groups as well as relationships with people outside of Ops. As I see it, all of the *Ops initiatives are attempts to fix the brokenness in communication that traditional software shop organizational charts create; managers and up need to realize the cost in agility that comes with creating silos. On the other hand, there is a clear benefit to specialization and building service groups around specific disciplines once a company gets to a certain size. I don’t have a good solution to this problem but spend a lot of time thinking about it… however, I do know it pays to meet the people you are working with face to face, have a beer and understand what drives those groups to make the decisions they do. I sometimes wonder if doing “embedded engineering” is the right approach, with engineers from all of the silos sitting together for the duration of a cross-functional project. If anyone has any thoughts on this I’d love to hear them.

March 18, 2010 cloud, communications, devops, performance

DevOps Documentation

In a previous entry I wrote that the key to removing the wall between developers and operations is communication. I wrote about becoming involved in your co-workers’ meetings and understanding your co-workers’ needs, and this is of course very important, but sometimes it is best to have things written down, because your co-workers aren’t always around to answer your questions (ops people who have tried calling developers at 4am know this all too well).  Good documentation is often toted as the answer to all of life’s problems, but we never make time for it. I’ve found a few ways to reduce the barriers to creating documentation, which I discuss below.

First, documentation needs to be revision controlled and live with the code, as doing so will reduce the cost for the developers to create documentation and help keep track of changes to documentation. This also means you don’t use binary formats for your documentation–no OpenOffice Doc, no MS Word, no format that you can’t store in git, svn, or whichever revision control system your company uses. You must be able diff revisions. Documentation stored primarily in plain text is ideal because plain text is a universal format; plain text can be emailed to anyone, edited by anyone, read by anyone and easily manipulated with tools readily available to both developer and operations.  My current choice for documentation is ReStructured Text, which you already know how to write even if you haven’t seen it before. ReST is a plain text format that evolved out of the docutils package and focuses on simplicity and clarity of meaning.

Furthermore, documentation that will be used by the developers and ops people should live with or near the code that the documentation is for so that the docs are easily accessible to both groups. Documentation stored in revision control also means that you can set up commit hooks that trigger alerts when the documentation changes. If you use a web-based system for browsing source code that system probably offers an RSS feed that can notify you of changes to files, so you can see when your documentation has changed without leaving your RSS client. The automation possibilities are endless–if a specific source file got updated but the docs didn’t? Send an email to the person who made the commit asking why.

Keeping the documentation within the source tree has the advantage of the documentation always being checked out with the code, and thus the most recent revision is available to all the developers, and the ops people keep up with the source tree as they work with the documentation.

The DevOps Dialogue Document

One of the first documents that an ops person looking to bridge the development divide should create is a dialogue document. This is a document that the developer and the ops person work on together that tracks all of the information needed to handle the care and feeding of the software. What should this document look like?

Administrative Details

  • A description of the software role and purpose.
  • A contact in development, a contact in ops, and a contact in QA. These are the people that can be bugged about issues with the software, and these are the technical, not managerial, contacts.

Operating Requirements

  • Disk space required for installation, disk space used in normal operations, disk space used by logs, disk space used by data, and estimates of growth rates.
  • Memory requirements.
  • Network requirements, including ports the software listens on, connections the software makes to other services, protocols used (at all layers), if SSL is required, and so on.
  • OS requirements, such as platform, distribution, release of distribution, kernel versions, patch versions, word size (32 or 64 bit), other unique OS requirements.
  • Environment requirements, such as libraries required, variables that need to be set, shells that are required, users and groups that need to be on the system, and more.
  • Details on how to start and stop the software.

Configuration Details

  • Details on how the software is configured; is it via a config file? Is the configuration in a database? Is there a way to change the running configuration on the fly?

Monitoring & Debugging

  • How does the software get monitored? Is there a way to have the software report status? What about performance monitoring?
  • What process do the developers use to debug issues they encounter in the software? For example, is there a mechanism to get a stack trace, such as Java’s handling of SIGQUIT?
  • How does the software respond to common error situations like out of memory or out of disk space, or being unable to bind to a port? What about handing of bad input?

Backup & Restore

  • How does the software store state, and can you easily backup and restore that state?
  • Can you do a backup while the software is running and get a restorable backup? How can this be tested?

Security

  • What privileges are needed to run the software?
  • How is input validated?
  • How are any authentication tokens (passwords, certificates, etc) stored?

There is a lot more that should go in each section and many more sections that could be added; the above is an example that you can use to start your document.

At the last Boston DevOps Meetup, @hercynium mentioned that he uses the FCAPS model to figure out what he needs to know about software he is going to deploy and manage. I hadn’t heard about this model but after some quick research it looks like an excellent reference for helping you build your dialogue document.  From the Wikipedia entry:

FCAPS is an acronym for Fault, Configuration, Accounting, Performance, Security, the management categories into which the ISO model defines network management tasks. In non-billing organizations Accounting is sometimes replaced with Administration.

These topics map well to the items that developers and ops people both need to understand about the software they are working on together.

No software will have the correct “answers” for the dialogue questions, and that’s not the point. You’re trying to start the dialogue that gets everyone thinking about software outside of their silo. I’ve written the questions above from the perspective of an ops person, but the developers should add their own set of questions — maybe a section on what the production environment is like and how software will be pushed to production. Since you are storing this document in plain text along side your source code under revision control you can easily check in new answers or questions and have those changes be seen by the developers on next update.

Developers and operations people lament the perceived lack of documentation and everyone agrees we need more. The purpose of the dialogue document is to create the documentation that is needed in the lowest cost way, so don’t try to make the perfect document from the start. Embrace the iterative and evolutionary nature of Agile and grow the document as your understanding of the software grows.

February 23, 2010 communications, devops, documentation