THE OMNI SHOW

Andrew J. Mason: You're listening to the Omni Show, where we connect with the amazing communities surrounding the Omni Group's award-winning products. My name's Andrew J. Mason, and today we talk to Dave Lonning, documentation wrangler for the Omni Group.

Andrew J. Mason: Hey, everybody. Welcome to another episode of the Omni Show. My name's Andrew J. Mason, and today we're honored to have Dave Lonning, documentation Wrangler for the Omni Group, hanging out with us and sharing a little bit behind the scenes of what goes into the documentation process.

Andrew J. Mason: Dave, thanks for joining us today.

Dave Lonning: Yeah, thanks so much for having me. It's good to be here.

Andrew J. Mason: Well, Dave, let's first jump in, and I got to say, documentation Wrangler, I love that job title because I think it accurately reflects the nature of the work of rounding up appropriate software knowledge. But break that down. What does a documentation wrangler do?

Dave Lonning: Sure. Yeah. So documentation wrangler at Omni is a fancy way to say technical writer, but, specifically, I am responsible for creating and maintaining the user facing documentation that we produce along with each of our apps. So if you look in any of our apps on Mac or iOS or iPad OS, you'll find the in-app help via our menus there. Also, you'll find it on the website at support.omnigroup.com in the manual section. So I produce the new versions of that every time we put a new version of one of our apps, and I make updates along with the point releases to the apps as well.

Dave Lonning: I also have a couple of other hats inside Omni. I work on some of our marketing materials, so sometimes you'll see posts on our Omni blog that are credited to me. I do some work on our newsletters, so if you're subscribed to the Omni newsletter, you can read that. We're putting those out about once every quarter.

Dave Lonning: That's pretty much it as far as what I do regularly. There's a bunch of other stuff internally that goes on, but in terms of the stuff that people see on the outside, that's it.

Andrew J. Mason: It's so funny, but to me, documentation is like the unsung hero of software. The software's front center, but out of nowhere, there's this safety net. If for whatever reason you don't know how to use a feature or do something, it's there silently ready to support you. And I think it's so cool that our team invests in being able to make sure that people know the software and have an opportunity to learn what each feature means.

Andrew J. Mason: Maybe walk us through your history with the Omni Group. How did you first start? How did you first hear about the Omni Group? And walk us through a little bit of your timeline.

Dave Lonning: Sure. I started with Omni in 2011. In fact, I remember it well. I believe I started the Monday after we had just learned of the passing of Steve Jobs. So that was a really momentous and historical day for everyone in the ecosystem of app development around Apple. And so it was a somber mood. There was the knowledge heavy in the air that we were moving into a new era for Apple stuff.

Dave Lonning: And it was cool because when I started at Omni, there was that feeling walking into the offices that I was walking into an organization that was really deeply steeped in the Apple ecosystem and the Apple history. And just in terms of people's relationships and experiences going back years and even decades, even at that time of interaction with the platform and the people there, and it really felt like I was stepping into something special.

Dave Lonning: I've been with Omni since 2011. It's coming up on 11 years now. And over that time, I've had the same role as documentation wrangler. And what that has meant over the years has morphed and changed, but at its heart, it's always about trying to provide the very best possible supporting documentation resources that we can for our customers that go right alongside with our apps.

Andrew J. Mason: Oh my gosh, Dave. Where to take this conversation next?

Andrew J. Mason: I guess one of the directions that my mind originally goes is this misnomer people have about a website, software. The gap in between publishing makes people think of it as just this snapshot in time. Like here it is. I have a website. I'm done. And you're not done because it's more of a conversation, and the more of a passage of time that goes by, the more stale that conversation gets. Maybe the more fresh things that there are to say about that website or software documentation. How do you manage that dance? And with the advent of the Internet, there are just so many entry points somebody could have to experience with software. How do I know how to approach the end user about assuming what they may or may not know already about documentation, and how do I even get that conversation started?

Dave Lonning: That is such a great question, and I think it is one of the biggest questions that we in documentation have been grappling with since, well, forever, but particularly since the inception of the Internet. Because when you talk about that conversation, back in the day, when you could assume that a person was approaching learning a task through a textbook, whether it's a reference manual that accompanies a piece of software or any other learning experience, you can provide a framework through a linear presentation in a book. Even if it also acts as a reference manual, like a dictionary, you can envision how your reader is going to arrive at and approach the topic that you're trying to teach them about, whether it's a piece of software or something else.

Dave Lonning: But with the arrival of the Internet, and search, you can no longer assume anything about where your reader is going to start their conversation with you. And that has been part of the process of iterating on how we design the documentation has really been transitioning from this idea of, okay, this is a book that if someone's committed to learning how to use one of our apps, they're going to sit down, and they're going to work through the book from comfort to cover. And by the time they've done that, we can feel pretty confident that they're going to be well versed in an understanding of how the app works and how they can get the most out of it.

Dave Lonning: Google blew that completely out of the water. Now, when you want to do something with an app, you go there and you type in a search. Like how do I draw a diagram, an OmniGraffle, or how do I set up a project in OmniFocus, or how do I track a project in OmniPlan? And not only can we not assume anything about where a person's going to end up after those search results, we really have to start thinking from the perspective of designing all of the content that we create as a potential first stop for someone who's looking for these answers.

Dave Lonning: And we also have to try to craft it in a way that's going to be appealing to SEO and in a way that's going to actually be answering the questions that people are actually asking. And that was a big part of our shift toward this more reference-style approach that tries to atomize things a little bit more and make it more immediately evident that the content you're looking at on a given page that you find in our documentation is going to be relevant to you. Because, if not, people are going to end up on a forum somewhere on Substack or on one of the many wonderful third party sites that are doing great jobs at answering a lot of these questions. But as long as we are producing this content as well, we would love to be able to present the most useful resource possible that's going to appear as high in the search results as possible.

Dave Lonning: And so, as a shorter answer to your question, I think it really is the same trajectory that a lot of people thinking about documentation have taken as they've moved away from this long form. Like people will read a book to learn how to do this to people will read the first hit that they find on Google as the way to figure out how to do this. And so responding to that and being prepared to have that conversation begin anywhere is where our head is at when we're thinking about solving this problem.

Andrew J. Mason: Wow. And with that, you have taught me something today. I literally never before this moment have had the thought about when software comes in boxes, it is frozen in time, and it's easier to have a more synchronized conversation about that software. As soon as the Internet comes out, it's a moving target. When you publish something, it's never done. There's no there. Something will change, the conversation will change, and things will be out of sync, out of date. And it does make me understand this more tutorialized nature that maybe third parties would decide to take where it's like, hey, if you're trying to get this specific thing done in the software, here's how you do it.

Andrew J. Mason: But if you're the one creating the blueprints for the house, trying to tell you where every nut and bolt is supposed to lie, and if somebody needs to know how that nut or bolt works in the house, the chances that you're going to hit a gap in knowledge that maybe they require other pieces of information before they hit that nut or bolt, what a mammoth task, what a huge challenge that is.

Dave Lonning: Yeah. Right. And I think some of that can be addressed. Again, this could very easily become a "Let's talk about how to make documentation that is going to help people the most" episode, and it would be great to cover some other things, too, but I do think a lot of that comes into the way that we design information that appears on a webpage in terms of the sidebar structure that may indicate other resources that are immediately accessible. So if someone lands on a page body that answers one part of their question, maybe they'll seize that in the sidebar there's some other part of their question that they could leapfrog to and find the answer there. So there are solutions out there.

Dave Lonning: In terms of our apps, we do still have the opportunity that many, I think, software developers these days are moving away from. To conceive of our documentation product as a deliverable that does have markers in time that come along with our major version releases. When you think of that in contrast to a lot of web apps or apps that you download on your phone that use a subscription model, or other may not be an immediately apparent model for how their revenue is generated. Just take any of your social media sites, for example. They don't have versions that are user facing. You go to twitter.com, and it's just Twitter, and you don't really think about it. They'll add features, and maybe that'll move the needle a little bit, but you never think, oh, we're at Twitter 4.0. Here's a new reference manual for Twitter.

Dave Lonning: Whereas we are still very much in that mode of, okay, we are reconsidering the app from the ground up. This is a great opportunity to make a lot of big changes at once, and we can rev the docs along with that. And it gives us an opportunity to rethink some of the ways that we present the information there. And that's a really cool opportunity to restart that conversation.

Dave Lonning: I think that is pretty neat, because it does give us that hybrid approach where, while we're not producing books that go along with things anymore, we do have these moments in time that can act as pivot points for us. The one exception for that being OmniFocus for the web, which is our first app that is deeply intertwined with that idea of this is a service that we're providing on a continual basis. The only way to get OmniFocus through the web is as a subscription, and so we have the opportunity to approach that a little bit differently. But we're still very firmly committed to the ability to, if you want to buy our apps as a one time purchase, or go through the subscription model, but that's a topic that's far afield of what we're getting into today, no doubt.

Andrew J. Mason: No, this is great. I'm interested actually in how this plays out currently. So we talked about snapshots of time, boxed software. The documentation's done. Fast forward to today, where it's almost real time collaboration with OmniFocus 4 in the Slack channel. A test build gets made, and there's immediate user feedback, and things can change about how the software is presented to the end user almost overnight. How do you handle that process and documentation?

Dave Lonning: That's a great question. Yeah, this process for OmniFocus 4 has really been a unique one, I think, in our approach to app development. Every time we release a new version of one of our apps, we iterate on the process, and we are always trying to figure out new and better ways that we can deliver an experience to our users that is going to meet them where they are. We have a lot of internal, very strongly held beliefs about good design practices and ways that we want our apps to behave and interact with what people have experienced from us before as well as where the platforms are moving and what our opinions are on this continuous project of development and refinement and improvement that we're engaged in.

Dave Lonning: And I think one thing that's made the process with OmniFocus 4 so unique is the level of interaction integration that we've had with our amazing group of testers and users who have been providing feedback for us. And it's really been an unprecedented level of collaboration I feel like we've had through this process that's really brought us to a place with OmniFocus that, at the start, I, personally, could never have seen it going. And that's just so exciting for me because it's resulted in something that when I come back to the app after each of these major internal revisions, I pick it up, and it's like a eureka moment for me. Because I'm seeing something that has come out of this collaboration and turned into a feature or an approach to a way that the app can be used that's not something that I personally might have come up with or thought of at all.

Dave Lonning: And so that has just been really inspirational, and also has been driving some of the way that we've been developing the documentation along with it, because some of our previous development strategies have been a lot more internally driven, I think. Along these ideas of preset design specs that we've had. And this one had that. Around a year ago was when we, I think, really first started this process of the external testing, if I'm recalling correctly. And at that time, we had done a lot of work internally for what we wanted OmniFocus 4 to be. And we were really happy with where it was.

Dave Lonning: And then we started getting all this amazing feedback, and it has evolved into something that is just what you see now when you're participating in the test. And that's amazing and wonderful, and means the documentation that has started a year ago based on those initial blueprints has had to change a lot. And so now I feel like the documentation is in an iterative formation that's coming alongside the rest of this consolidation of the features as they exist now and as they're really coming to rest in this final phase of the design freeze and the refinement into what you're going to see in the finished product.

Dave Lonning: I guess that's all a long way of saying that I guess over the course of the docs development for this project, there has been a new component of incorporating the collaborative feedback mechanisms that we have built out to go along with this development process.

Andrew J. Mason: Maybe I'm being a smidge too dramatic about it, but it makes me think you're probably one of a handful of people ... I'm sure there's other people that know very well every corner of the software and how every single feature works. But there's a sense in which you might be the single source of knowledge for every single thing that works in Omni software. Because in order to teach, you have to know. So in order to document, you have to have interacted and understood all the different parts of the software. What an interesting career challenge. Is that true? Do you literally have to know everything about the software?

Dave Lonning: That is a great question, and the short answer is yes. Yes, I do, in the course of developing the docs for one of our apps, need to familiarize myself pretty much with how everything in the app works to a degree of fidelity that we want to reflect in the documentation, which is a pretty high degree. We've had to put up some guardrails there. If you look at some of our past documentation products, you can see examples where we have gone to a very, very, very thorough extent of really documenting not only everything but also processes and interoperability with things that aren't exactly pieces of the app that are shipped inside it, but scripting languages and other things that have various ways of interacting with the apps.

Dave Lonning: Yeah, and so there is always that back and forth of how much of this app's existence in an ecosystem of other technologies are we going to include as part of the documentation product? Because that does threaten to allow it to expand infinitely as we create these technologies on top of it. For example, Omni Automation. Amazing, powerful tool set that all of our apps support that can turn them into pieces of a massive machine that you're bringing in things from all over to power your workflows. And that's amazing, but we made a decision really early on in the development of Omni Automation support for our apps that we weren't going to document how to do that within our reference manuals.

Dave Lonning: And, thankfully, Sal has done an amazing, amazing amount of work and an amazing job of producing a huge repository of documentation specifically for Omni Automation, which you can find omni-automation.com. So that's an amazing resource that, thankfully, he has taken responsibility for, and we are so grateful for, but an example of something that doesn't live inside the manual, and that I don't have to become a master of myself in order to account for as I'm writing the docs.

Dave Lonning: Another caveat there is we've got four very powerful applications: OmniFocus, OmniGraffle, OmniOutliner, or an OmniPlan. And when they're in the middle of their development cycle, I only really have to be familiar with the changes that are happening in a given point release. So maybe we're adding or changing a feature slightly. Those are the things that I need to make the most sure are addressed, accounted for, incorporated into the docs. If there are any other changes or fixes that need to be made, those go in, too. That's a bug-driven workflow in our internal bug tracking system.

Dave Lonning: But as long as we're in between these major releases, I don't have to have the entire app in active memory. So, thankfully, for example, right now, we released OmniPlan 4 for Mac, iPad, iPhone. Over the course of the past couple of years, and over that time, they were living in my head, and I could do just about anything with OmniPlan that I could imagine or that would go into the docs, which was pretty much everything. Right now, if you asked me to do all of that stuff, I couldn't immediately do it, but I could go to the docs and I could figure out how to do it. So that's where OmniPlan is in my brain right now. Ready to be brought back when we have to do a new point release, but not loaded into active memory since we're not working on the next major version of the app right now.

Dave Lonning: Right now, OmniFocus is big inside my head because that's the one that's receiving the most active development in terms of where the project is in its life cycle in the development of this new major release. So there's a whole lot of OmniFocus rattling around in my head. Coming up next, we have OmniGraffle, which is, as Ken alluded to in his roadmap blog post, the next big thing that we're already doing a lot of work on and thinking about internally. So that's starting to creep up on the horizon as another one that's going to be taking up a lot more space in my head.

Dave Lonning: OmniOutliner is in a relatively stable state right now, and I feel like the most recent work that I did for it with OmniOutliner 3 for iOS and 5 for Mac got me to a place where I know OmniOutliner really well. It feels like a good friend. And I feel like I actually don't have to do quite as much reaching when I need to find that frame of reference there for what it can do. Partially also because I use it all the time as part of my writing.

Andrew J. Mason: I'm curious now about the rhythm of your job, too, because it sounds like there's never a monthly, weekly, daily rhythm there. If things are always changing, and you're always cycling through software, the upside of that, you never get bored with things. You're not working in one singular piece of software for too terribly long, so that's pretty cool. But do you have anything that resembles "This is kind of how the structure of my day goes. Even if I'm working on different stuff, this is how things work out?"

Dave Lonning: Man, this is interesting, because as very long time fans of the Omni Show may know, I was on the show once before for our 10th episode in 2018. So I think that probably is enough time in between appearances to justify me popping up again on the feed for people. I bring that up because what counted as a typical day in 2018 has changed a bit between then and now in 2022. We have transitioned to this remote first workflow. There's still a lot of the same structure to my day that I had back when we were all seeing each other regularly in the office, but some things have changed as well.

Dave Lonning: So a typical day really involves me booting up the Mac, looking at the list of bugs that I have assigned to me, looking at the list of dates in our bug tracker to see what the next milestones are that are coming up in terms of the development of all of our apps. Seeing what's assigned to me, seeing what might be blocked by anyone else that I'm working with on a project, and just picking up with the writing from there.

Dave Lonning: And we've held onto our traditional lunchtime at Omni, which is 12:30 to 1:30 Pacific Standard time, so my mornings typically start a little bit later, like 10:00 or 11:00, depending on when meetings are or when other stuff's going on. And then I'll work until about seven in the evening. And that time is full of regularly scheduled meetings, like product meetings; various team meetings within the Omni organization; one-on-ones with folks; either scheduled regular check-ins with the product managers or with Ken to just talk about what's been going on over the past week.

Dave Lonning: And, lately, I've really been trying to embrace the idea of doing more just informal coworking and collaboration with people face-to-face. I'm an introvert, and so if I don't have some structurally imposed reason to get together with people to work, I'm less likely to do so. But really over the course of the past couple of years of this working from home, I've come to realize just how important it is to collaborate with folks, to see people, even if it is just face-to-face over the video. I think it is such an important part of that.

Dave Lonning: And so figuring out how I can incorporate that more formally into how I incentivize myself to do work. Because a lot of the times in this role, it can feel pretty siloed. This is a common experience for a lot of writers, where it's that trope of going off alone into a dark cave for months, and just banging on a keyboard for a long time. Finally, coming up, holding this thing, this tablet, or this sheaf of paper that you're waving front of people. And you're like, "Look at this." It's like trying to formalize systems of escape from that mentality of that retreat into a cloistered space where you generate a product and then you bring it out.

Dave Lonning: Because I feel like one of the things that I've learned over my career here has been that feedback and iteration really is your best friend, and getting feedback early and often, and aligning with your team because everyone really has the same goal. At the end of the day, everyone wants to produce the best product possible, whether it's a software product or whether it's a documentation product. Everyone wants to make the best thing that we can for our users, for the people who are reading the docs, for the people who are using the apps. And whether that's getting into a regular feedback loop with our designers, or our product managers, or our engineers, or our testers, or our support people, it's keeping those lines of communication open.

Dave Lonning: And so I guess, long story short, a typical day for me would be alternating between going into the cave, working on some writing. Whatever it is, whether it's an update to an existing piece of documentation, or development iteration on a new product. And then coming out of the cave, and entering into one of these feedback loops. Talking with the people who, on whatever project I'm involved with, are the ones who are most closely collaborating with me to give their thoughts on the work that I'm doing, and for me to be able to give them my thoughts on how the product is going. And I guess probably oscillating between those two work modes, and then just going to regularly scheduled meetings, I guess. That probably would be a way to describe it.

Andrew J. Mason: Oh my gosh, Dave. I think all the other introverts out there are nodding their heads right now, and me, too, to some degree. This idea that if I don't have this externally imposed structure of interaction with other people, then I might never talk to another human being. The whole saying about how solitude's great but isolation is not so much.

Andrew J. Mason: I do appreciate how precise you probably have to be with your language as you're saying exactly how to do something. But I also know that meaning sometimes changes from person to person. Has there ever been a time where you felt like, man, I've come across very precisely, we've communicated clearly how this is supposed to be, but when we unleashed it on the public, it just was not how the meaning was received at all?

Dave Lonning: Oh, man. No, that's a great question. I can't think of an exact example off the top of my head, but your asking this question reminded me of another, I think, long arc trajectory that I've been on in this role with Omni over the years, and I think it's reflected in our current documentation style as well, is that, man, I am a lover of $100 words. I'm a lover of flowery language. I'm a lover of jargon. If I can use a 10 letter word where a four letter word will work, that is my gut instinct. And what I've realized over my time here and just generally thinking about this is that is great when you're having fun, having a chat with your buddies, or when you're doing other things. But when you're trying to communicate, keep it simple. Just use the simplest, most direct language possible to communicate with people.

Dave Lonning: And so even now, I was just getting some feedback from one of the people on our support team about one of the drafts of the docs for OmniFocus 4. And she found a couple of examples of words that I had used that are like, is this really as straightforward as we want it to be? And she pointed it out, like, no, we can make that way simpler. We can say something that's more simple, more direct that says the same thing. And that's really all upside. Just really winnowing down.

Dave Lonning: I guess, put another way, words are cheap. It's very easy to use a lot of words to explain something. Kind of as I'm doing right now, I can start talking, and if you let me talk for long enough, I'll eventually be able to explain what I'm trying to say. But taking that initial output, and then crystallizing it, refining it, honing it down, getting it just really polished, that's hard. Taking that initial output and then revising it down into really what you're trying to say is the work of the writer, and the editor, and that feedback loop to really make sure that we're communicating what we want to say in as simple and direct way as possible.

Dave Lonning: Especially because, over the years, we've produced many localizations of our both app interfaces and reference manuals, and I've worked with localizers, and the more simple, direct language we can use in English, the easier it's going to be for everyone involved with this process to either translate it or understand it if they're not native readers of English. It's all upside.

Dave Lonning: And so continuing on that voyage and that journey, I guess, has been a constant exercise in doing what you asked as the question, I guess. Just realizing where we're saying things that are really unnecessary for communicating what we're trying to say, and then parsing that down.

Andrew J. Mason: Dave, this has been so fun and so educational for me. Thank you so much for spending time with us. How can folks get in contact with you if they're interested in reaching out or sharing something about documentation, or even just have a question? How can they do that?

Dave Lonning: Yeah, if you'd like to get ahold of me, just fire off an email to support@omnigroup.com, and put documentation somewhere in the subject line or the body of the message, and I'll be able to see it that way. The support team will forward it on over to me, and I'm definitely always looking for ideas about how we can make the docs better. Or if you find something wrong, heaven forbid, definitely want to get that fixed, so please don't hesitate to drop me a line via our support channels.

Andrew J. Mason: That's awesome, Dave. Thank you so much. We're honored to have you today.

Dave Lonning: My pleasure. Thanks for having me on.

Andrew J. Mason: Hey, and thank all of you for listening today, too. As always, you can drop us line @theomnishow on Twitter. We'd love to hear from you there. You can also find out everything that's happening with the Omni Group at omnigroup.com/blog.