THE OMNI SHOW

Brent: You're listening to The Omni Show. Get to know the people and stories behind The Omni Group's award-winning productivity apps for Mac and iOS. Music.

[MUSIC PLAYS]

What a lovely tune. I'm your host, Brent Simmons. In the studio with me today is Dave Lonning, documentation wrangler at The Omni Group. Say hello, Dave.

Dave: Hello, Dave.

Brent: Very well done. Thank you. So, as a documentation wrangler, your job, roughly speaking, is writing and publishing the documentation that ships with our various apps' Mac and iOS versions. So I guess my first question is, these days, why do we even have documentation?

Dave: That's a great question. I think, put simply, in the case of our apps here at Omni, we make apps that are really powerful. And with that power comes a lot of versatility, a lot of options, a lot of menus, a lot of components that aren't all necessarily obvious as to what they can do at first glance. And so, what our documentation does is it steps in, and provides a little extra help for users who would like to take full advantage of all of the powerful tools in our applications.

Brent: That's cool. I mean, obviously, we design to make things user friendly and obvious. But when you have apps as powerful as these, the written word has to step in, I guess.

Dave: We see it as part of the team along with UX, and support, and design, and everyone who is working together to try to make everything as accessible as possible while also not sacrificing any of the power and flexibility that we're known for with our apps, here.

Brent: Even on iOS, which is not the easiest thing in the world, but-

Dave: Yeah.

Brent: You crammed quite a bit in there, I guess.

Dave: Yeah, especially over the past few years with the goal of reaching feature parity with our Mac apps. Some of that's still in progress. But we are bringing a level of complexity and power to the iOS space that is not that common. And so, unlike a lot of other iOS apps, we feel like it's important to support that with full documentation of all of the features and UI components of the app.

Brent: So I'm curious about the evolution. When I was a very young person, I'd buy a floppy disk that came in a Ziploc bag with some Xeroxed ten or twenty pages, or something. Then I noticed that things got a little bit better later on. We got actual boxes, and bound, printed manuals, and everything. What's happened since then?

Dave: When I started at Omni was a little bit after the heyday of those boxed software, with the big maybe spiral-bound or glue-bound manual that you'd get in the box along with the software disks.

Brent: Though Omni did produce those, back in the day.

Dave: Yes.

Brent: Bought them in the store. Yeah.

Dave: Yes, they did. And wandering around the office, here, you can see, as trophies, up on the shelves, some of the old boxed versions of our apps. But when I started, all of our distribution was done digitally through the Mac App Store, as well as our Omni store and the iOS App Store. And so, the challenge, since I've been here, has been to figure out the best way to deliver digital equivalent versions of our documentation, both bundled along with the apps and as separate standalone resources that people can reference no matter where they are.

Brent: So when you started off here in 2011, am I right?

Dave: Yep.

Brent: I think, in those days, I was writing apps, and we were using ... Apple had their own thing that I remember doing. Did we use that at the time? Do we still use that?

Dave: On the Mac, the Apple Help viewer had their own proprietary format for organizing and presenting help. Apple would use it for all of their Mac apps, and many other third-party companies did too, including Omni. We used the Apple Help viewer. We actually authored our help at that time in OmniOutliner, and used a Python script to port that over to the Apple Help book format.

Brent: I'm trying to imagine what that script looks like. Do we still have it around somewhere?

Dave: I think it's still somewhere in our Subversion repository, yeah.

Brent: Yeah. I might try and publish it, just for jazz. We'll see. It'll either be in the show notes, a link to it, or it won't. I'm sure it looks insane, though. And we, obviously, don't still use that. We've moved on from the Apple Help format, I take it.

Dave: Yeah. That's in the rear view mirror for us. It became less widely used a couple years after I started here, and so we started looking for other alternatives that would fulfill a similar function.

Brent: So the process has been evolving, and our toolchain now generates a couple of different formats, I take it. HTML, EPUB ... And so you're using MultiMarkdown, do I understand right, to write documentation these days?

Dave: Yeah. That's right. We started ... As we were investigating opportunities for moving away from the Apple Help viewer that was no longer fully supported, we looked into a bunch of different options. And we did hit on using HTML and variants of HTML formats to present the help, both in the app and in portable formats. And over the years of iterating on how best to create this HTML, and looking for the ever-elusive single universal source of truth that we could author in, that we could then put out as an EPUB, or a PDF, or an in-app help file, we have ended up settling on MultiMarkdown, which is ... If you're familiar with Markdown, MultiMarkdown is the same thing, but with a few more additional features that lets us add more structure and enhanced multimedia aspects to the help books that we make.

Currently, we have an in-house developed toolchain that takes MultiMarkdown and produces help-book-style output, as well as output that can use a print CSS and be made into PDFs really easily. And we're working on figuring out what the best and most useful formats are going to be moving forward from that baseline.

Brent: Way back, many years ago, when I was at UserLand, we had the mantra of "scalable content" for awhile. And the idea is ... We had a CMS that was making websites, but we wanted to be able to turn that into other things. After all, it's just printed words and images. It could be many different things. We didn't necessarily go very far with that, but it sounds like, here at Omni, we've actually done quite a lot with scalable content, as we used to call it.

Dave: It's really been an odyssey moving from building out books, almost handwriting the HTML ... That's actually what we were doing in the earliest cases of our iPad apps, when I started here. When I started at Omni, we had OmniFocus for iPhone, and then OmniOutliner, OmniGraffle, OmniFocus, OmniPlan, and OmniGraphSketcher, all on the iPad. And they all had hand-coded HTML pages within them that were their in-app helps. And that's fine when you're launching a brand new app, but when you start needing to maintain versions, and update all of that, going in there and adding paragraph blocks by hand and making sure that everything is consistent becomes a big, complicated headache.

Brent: And you mess up one tag somewhere, and the rest is all italics.

Dave: Yep. We've definitely made great strides from that point to a really robust system that helps us make sure that everything is consistent. And when we put out a piece of documentation in one format, it's going to be the same everywhere.

Brent: That's great. So, aside from being able to get to these things from within the app, do we also provide downloads? So anyone can just ... Say I want to ... I mean, I've got OmniGraffle on my Mac, and I'm learning it. This is a true story, by the way. And I want to read my manual on my iPhone on the bus to work. How do I do that?

Dave: If you go to our support website, that's support.omnigroup.com, you'll see a link to our manuals, and that gives you a breakdown of all of our current documentation by app. And so you can go to the "OmniGraffle 7 for Mac" section, and you'll find links to the various formats in which our documentation is available.

As you scroll through the apps, you'll see that there's a big of variance right now, at the time we're recording this, because, as always is the case, in my experience in the software world, things are works in progress when they can be because we're always trying to find the best solutions to the problems that we currently have. And, in documentation, as with a lot of our apps, the best opportunity that we have to fix a whole bunch of problems at once is at a major point release.

So, for example, when OmniGraffle 3 for iOS shipped, that was a paradigm shift in our approach to documentation for our iOS apps. And you'll see that when you go and look at the docs for OmniGraffle 3 for iOS. OmniGraffle 7 for Mac ... Docs look a little bit different because they were created when OmniGraffle 7 was released, under a slightly different approach.

Brent: So then when OmniGraffle 8 comes out, will it switch to the newer paradigm?

Dave: That's the plan, yeah. We're moving toward standardizing on the type of doc that you'll see for Graffle 3 for iOS and Outliner 3 for iOS right now. We do definitely want to make sure that those hard copies, as with the EPUB version for OmniGraffle 7, are available, or perhaps a PDF version. Whatever ends up being the most useful and at that nexus of utility and efficiency for us to generate and keep current. Because, as you'll see if you go and look at our documentation on the support website, there's a lot of stuff there. And, yeah, we want to make sure that it's always up to date and consistent. And thankfully we now have the automation tools that really are going to make that possible.

Brent: So I'm a little envious of your job in the sense that ... With writing documentation, you have to talk to just about everybody. Which ... I talk to one person every two weeks, and then it gets uploaded to the web. But you talk to everybody all the time, because to write documentation, you have to talk to support, project managers, engineering, design, testing ... How does that all work for you?

Dave: Yeah, it is a really great part of doing documentation here at Omni, that on any given day, I might interact with someone from support, and someone from the product manager team, and someone from the UX team. And even an engineer or a tester in the course of identifying issues, making sure that fixes to them are accounted for in the documentation, or collaborating with a PM to make sure that a new feature that they're describing in the release notes is accurately reflected in the documentation.

Or if there's an issue that support brings up that might be a point of customer confusion, then I'll get together with UX and the support team, and we can look at ways that we could address that, either through, perhaps, a change to the interface or an update to the documentation that provides a more detailed explanation of how the user can do what they want.

Brent: So do bugs get filed against documentation the way they do against the apps, and everything?

Dave: Yeah. Depending on where an app is in its life cycle, the bugs work a little bit differently. But for any app that's currently in production, we'll just see a steady trickle of bugs come in as people have ideas, either from customers who might be confused about how to do something, or who find a typo, God forbid, or some other missing piece that might be able to be added to make the docs more clear. And then we will triage those bugs just like we would an engineering bug, and get them out along with milestones during the app release cycle.

Brent: Do we have an in-house style guide?

Dave: We have, at various times, had style guides. I mean, the short answer is "yes". The slightly longer answer is ... We would like to get that updated, because there's definitely an opportunity there to make sure that things are even more consistent between all of our apps.

Brent: I wonder if that style guide should extend also to blogging, and tweeting, and whatever else? At least for certain types of problems, it probably could.

Dave: I think ...

Brent: I love style guides, is why I'm bringing it up.

Dave: I am right there with you. This is a project that has been on the back burner for a little while, and I think once we have a little bit more bandwidth between releases, we'll be able to really focus on getting something that's comprehensive and that applies to all of the written communication that we do. Omni definitely is known for its tone of voice in terms of the way that it is engaging, and tries to be kind of warm and a little bit informal. Because we ...

Brent: But not breezy, right?

Dave: No.

Brent: Never breezy.

Dave: Not breezy, and not unprofessional, but kind of understanding that even when we're doing something really serious, like with OmniPlan, or creating a huge book outline in Outliner, we're still trying to have fun. We want the use of our products to be enjoyable, and we want our written communication to reflect that. And not be super technical, and dry, and dull all the time. We do want to be clear, and specific, and succinct, but ...

Brent: Yeah. Right. So we have how-tos and support articles, as well. Do you write those? Or does support write the support articles, and you write the how-tos? Or how does that work out?

Dave: Yeah, there really is a wide variety of support resources that we offer in written form on our website. And the way that tends to break down is ... If there is an issue where a customer encounters something unexpected, or there's otherwise some sort of incompatibility with an older OS version, or something like that, that falls under the troubleshooting category of support articles, and those are written and maintained by the support department.

Articles and written content, including tutorials and such, that are more about how to do things, how to accomplish certain tasks, or descriptions of the apps and their functionality, that's what falls under documentation.

Brent: Okay. That makes sense. And our support people are all writers, after all, because that's what support is, is writing all day long.

Dave: It is a really big part of the job, yeah.

Brent: Yeah. Except when it's actually speaking on the phone.

Dave: Yes. A lot of communication skills required. And working with the support team is one of the most enjoyable and most important parts of what I do in the documentation role.

Brent: So, my notes here have you as a world traveler. Born in Mexico, moved to Vermont, moved to Minnesota. Let's start with Minnesota. Why are you in Minnesota?

Dave: Well-

Brent: Because your parents brought you there. Why else?

Dave: Yes. My parents are both from the Midwest. My dad was born in Minnesota, my mom's from Iowa. They were living in Mexico when I was born, and my dad went to college in Vermont, and then they decided to move back to be closer to family, there in the Midwest, in Minnesota. And that's where I went to school, from kindergarten through college. And that was also where I encountered my first Apple computer.

Brent: Was it actually an Apple computer?

Dave: It actually wasn't an Apple computer. My uncle was the one in the family who was the big tech guy, and we tended to get machines that were ones that he was done with. So this was back in the mid to late '80s, and-

Brent: “Give it to the nephew!”

Dave: Exactly. No, he had just gotten a shiny new Mac Plus, and so he gave us his old computer, which was a Laser computer.

Brent: Nobody believes this actually existed.

Dave: L-A-S-E-R.

Brent: I'm going to have to Google this. A Laser computer.

Dave: Yes. This was an Apple compatible, green and black screen like an Apple 2C or E, and I remember using AppleWorks on the Laser to do word processing back in 1988, '89.

Brent: So how compatible is "Apple compatible"?

Dave: According to Wikipedia, which I just looked at before we did this, it was between 90 and 95 percent compatible.

Brent: That's almost good!

Dave: Many important applications developed by Apple could be run on the Laser. But, thankfully, my uncle decided to upgrade from his Mac Plus, and we were able to get ahold of that around 1990. And, yeah, it was on to the Performa, I think, in the mid '90s.

Brent: Oh, yeah. I had the Performa 405, which I bought from Silo.

Dave: Nice.

Brent: 90 days, same as cash. We did it. Paid it off, three months.

Dave: It was a good machine.

Brent: Yeah, it was. Yeah.

Dave: Yeah.

Brent: You were deciding where to go for school. As a Mac fan, you chose Macalester College in Saint Paul. Liberal arts school, where you studied something.

Dave: I started off as a philosophy major, but then switched halfway through to Asian Studies with a concentration in Japanese Studies, both the language and the culture. And that eventually took me to Japan. In fact, right after I graduated, got my first job teaching English in Japan, which was quite a trip.

Brent: Was your Japanese pretty good? So you could get around and do things? I'm sure you learned a lot more quickly, but-

Dave: Yeah. It was the sort of thing where I had a couple years under my belt from college, but, boy, that full immersion experience ... I ended up teaching English in a little town that was so small that its train station didn't have anyone working there. It was kind of on the honor system. You'd go through, and you'd just drop your ticket off in the turnstile, and then you just walk on through. And it was kind of surrounded by-

Brent: So, in other words, you could ride around for free.

Dave: The way the system was set up, you could if you both got on and got off at a station that was unattended. But as long as one of the two points had a person, or had some kind of a gating mechanism, then it was a lot harder to do that. And the place where I was leaving from was a bigger town, and so you had to buy at least one ticket there.

I was working in this little town with countryside that ... If you're familiar with the Tom Cruise movie "The Last Samurai"-

Brent: I'm positive some of our listeners are, yeah.

Dave: They filmed some of the scenes for that movie in this little town where I was working.

Brent: Oh, cool.

Dave: Yeah.

Brent: Was it beautiful?

Dave: Oh, gorgeous. You could really feel transported back, I don't know, 50 or 60 years just bicycling through the rice fields of this town. It was a great experience.

But the road from English teacher to documentation writer wasn't exactly straight through. After a few years of teaching English, I ended up working for a small company that produced English language localizations of Japanese video games. And we were using-

Brent: So after the "all your base are belong to us" fiasco, they were like, "We need Dave. Dave will prevent that from ever happening again."

Dave: I did bring a little native English expertise to the table, there. And since the company was so small, I ended up wearing a lot of different hats, doing some documentation writing in the form of producing manuals for these games, as well as some translation and project management work, interfacing with other translation people, localizers, in the Japanese companies. All of that done on Macs. We were producing PC software, but using Macs to do it.

Brent: Because Macs are just always how you make things.

Dave: Right.

Brent: That's always just been true.

Dave: Macs are how you make things.

Brent: Even when Apple was doing very badly, people were still using Macs to make things.

Dave: Yeah. And so that kind of gave me some of the groundwork that led to the documentation position here.

Brent: So, what prompted you to leave Japan and come work for Omni?

Dave: I was living in Japan in the spring of 2011 when they had the really big earthquake and tsunami that devastated the coast.

Brent: I remember seeing about it on TV. It just seemed extraordinary.

Dave: It was a really intense period. I was nowhere near the epicenter of the destruction, but it was ... Experiencing that and living through the aftermath caused me to do some soul searching, and try to figure out for myself whether I wanted to make my home in Japan indefinitely, or look for other options elsewhere. And I came down on the side of ... It seemed like I was ready to move on.

And so I started looking around, and it was around that time that a good friend of mine, William Van Hecke, former Omni employee, mentioned that this-

Brent: Great designer.

Dave: Yes.

Brent: And great guy. I love working with-

Dave: Yeah.

Brent: Yeah. He hasn't listened to the show, so we can say that.

Dave: Yeah. No, he was working at Omni at the time, and he saw that this job opening had come up, and he knew that I was a writer. And so he suggested that I should apply. And I figured, "You know? What the heck. I'll give it a shot."

Brent: So had you already moved here? Or did you fly out, or ...

Dave: No, I was still living and working in Japan, but when they offered me the opportunity to apply, I said, "Sure." So I got a plane ticket, flew to Seattle for a weekend, and had an interview.

Brent: With jet lag and everything.

Dave: Yeah, I was pretty keyed up. Sitting in the coffee shop a block from the old Omni location, and just kind of ... "What am I doing?"

Brent: Was that the Interbay location?

Dave: Yeah. But, yeah, I had the interview, and it went well, and-

Brent: Were you in Caffe Appassionato?

Dave: No, it was actually the old [Q Café], which I think they've moved over to Ballard. It was a really surreal experience, but really good, and apparently they liked what they saw when I was in there. I can't remember what I said, but ...

Brent: All a haze.

Dave: Yeah. The offered me the job, and I turned around and came back a couple of months later. In hindsight, I probably shouldn't have had my last day at work in Japan the Friday before the Monday when I was starting here.

Brent: Wow, that's abrupt, yeah.

Dave: Yeah.

Brent: You're still recovering.

Dave: Yeah. A bit of a rough transition, but ... No, it was great.

Brent: I mean, it'd be one thing if you were living in Seattle, and you just switched jobs, but you flew from Japan on the-

Dave: Yeah. But after about a week of jet lag recovery and apartment hunting, I found a place to settle in, and it's all been good since then.

Brent: So I hear you run a game here at Omni.

Dave: Yes.

Brent: There's a group of people who like to play roleplaying games.

Dave: Yes. This is something that I think Omni wears as kind of a badge of pride, that I was actually really looking forward to when I started here. Which was immersing myself, once again, in the geek culture of the greater Seattle area. And ...

Brent: We have all the best geeks here.

Dave: Lots of really, really wonderful geeks. And, yeah, so one of the first things I did, along with getting up to speed with the documentation, was looking for a D&D group here at the office. And sure enough, there were a whole bunch of folks who were playing when I started. And I decided that I wanted to run my own game. And since the winter of 2012, off and on, I've been running, actually, a Pathfinder campaign for several fellow Omni employees and a few friends from outside the office.

Brent: Half our listeners are cheering right now. "Pathfinder, yay! That's awesome." Then there's me, I have no idea what it is. I'll find out when I do the show notes, though.

Dave: Any time, if you want to sit in on a session, you're more than welcome.

Brent: Well, thank you. Yeah. So, your hobbies are ... Do you do a lot of gaming outside of this, or think about games?

Dave: Yeah. I mean, D&D and that type of tabletop roleplaying experience has been near and dear to my heart since I was in school, in junior high and high school. And so, along with running the biweekly games, I also like to paint minis and use the terrain to bring a battlefield to life, or a castle or wilderness setting, and stuff like that.

Brent: Oh, cool.

Dave: It's like building a diorama, or something. Like a train set, or something.

Brent: Do you have, or can you take a picture we can share for the show notes?

Dave: I certainly can.

Brent: Awesome.

Dave: I have a bunch of paraphernalia that's stored in my office here at Omni, and I'll give you a picture.

Brent: Cool. So we're on a bit of a roll. Last week was Ainsley. She's a cat person. I'm a cat person. How about you?

Dave: I'm a cat person, as well.

Brent: Yay!

Dave: Omni is, I think, known for its dog culture, which is wonderful. I was just listening to Ainsley's episode, and I think, like her, I've warmed considerably to dogs over the years that I've been here. But, at heart, I'm a cat person, and it breaks my heart that, where I'm living, currently, I cannot have a pet. Otherwise we would definitely have a cat.

Brent: Well, one of these days you'll live somewhere, and you'll have a cat.

Dave: Yes.

Brent: Or cats.

Dave: And there are plenty of fellow Omniites who are always offering to offer cat cuddles, so that's fun.

Brent: Well, thanks, Dave. How can people find you on the Web?

Dave: I am online at @zroundbls on Twitter.

Brent: Not "zroun-doubles". It's zroundbls.

Dave: Yes.

Brent: Well, it'll be in the show notes, anyway.

Dave: Yeah. It wasn't picked due to its unpronounceability, or anything like that. This was actually kind of an in-joke due to lots of texting with my friend William prior to starting this job. We kind of invented a nonsense language that included words like that.

Brent: Sounds like William, yeah.

Dave: Thus, a Twitter handle was born.

Brent: Cool. Well, I'd also like to thank our intrepid producer and fan of the Rocketeer, Mark Boszko. Say hello, Mark.

Mark: Hello, Mark.

Brent: And, especially, I want to thank you for listening. Thank you. Music.

[MUSIC PLAYS]