Documentation...the good, the bad, the ugly Part 1

In this episode of Workflow, Brian and Tom talk about creating documentation for projects. The good, the bad, and yes, the ugly!

00:46   What’s happening Brian and Tom (iPad Pro, Gantt)
05:31    Where we stand on documentation
12:54  How we structure our documentation at Rindle
17:57   How does Rindle document feature development?

Check out Part 2, Episode 20

Tom: 00:00 This is Workflow, episode 19. Workflow is the podcast that helps teams figure out the best way to work, collaborate, and get stuff done. Brought to you by Rindle.

Tom: 00:30 Hey everyone, I'm Tom.

Brian: 00:31 And I'm Brian.

Tom: 00:32 And we're the co-founders of Rindle, and this is our podcast, Workflow. Today we're talking about all things documentation. The good, the bad, and yes, the ugly. Cool, before we get started with that, what's goin' on with you, Brian?

Brian: 00:46 Nothing much, I'm excited that I'm getting my new iPad Pro today. So it was on my list to possibly try, and they came out with a new one, so I kinda bit and ordered it. You know, I'm gonna see how it is for me, but I have a couple use-cases in mind for it. One, is definitely handwritten notes, you know, just to use it as a writing tablet 'cause I have lots of scrap paper that I use to jot down things and maybe that will help keep me organized. So I heard that the handwriting piece of it and the conversion to text and all that stuff is pretty good, so I'm excited to try that. And then the other big use-case is also as a second monitor when I travel.

Brian: 01:34 So if I go away for a week, for example, and I'm still doing some work here and there I can actually leverage that for my workspace. Again, not a necessity, but something that could maybe help a little bit. And then to be able to take that instead of my laptop everywhere, which is a little more portable. I can do other things on it like media and things like that, so if I travel even for the day somewhere, grab that, and I can still write emails on it, I can still do all those things. A little more functional than a traditional iPad. So I'm pretty pumped about it.

Tom: 02:07 Cool. You'll have to let me know how that goes, I've read a couple reviews about them and people seem less than excited.

Brian: 02:16 I think people are still fired up that you can't have a mouse with one with even the latest iPad Pro. 'Cause there's no point to on the iPad, and there probably never will be. Maybe there will be. But now they have the keyboard, right, so they're very much competing with the Surface, right? And the Surface has like this keyboard that pops out, and very much like a computer, it's a tablet, it's a computer. So iPad is definitely, Apple's trying to definitely go that route, but you still can't have a mouse.

Tom: 02:42 Yeah, I think-

Brian: 02:43 So awkward to think about typing and then reaching and touching, right?

Tom: 02:48 I think the issue is iOS in general, like it's just very single app oriented. Like one app open at a time ... not that multitasking is that super important, but I mean, everyone has to do it to some extent, right? You're gonna look at a webpage and then write email, right?

Brian: 03:13 What if there's a ... I didn't research this yet, but I wonder if there's a keyboard shortcut to jump between apps. Like, if you ...

Tom: 03:20 Yeah.

Brian: 03:21 I think on the device you have double tap the home screen button, or whatever it is you do, you know, that would be useful. If it doesn't have that again, that's probably gonna be an awkward experience jumping between apps. We'll see.

Tom: 03:34 Yeah, that's what I've read, that it's like the same awkward experience that you have on your phone trying to do work.

Brian: 03:42 Well, yeah, I'm really thinking more using the keyboard and actually doing work, right?

Tom: 03:46 Sure.

Brian: 03:46 Like you're actually sitting down to type emails, or whatever it is you're doing, the problem using the keyboard is you're not holding it in your hand anymore. So it's like, okay now I feel like I should have a mouse, like I'm sitting at my desktop or my laptop.

Tom: 03:58 Yeah, we'll see.

Brian: 04:00 Yep.

Tom: 04:01 Well, let me know how that goes.

Brian: 04:04 I will report back to you. Cool. So what's going on with you?

Tom: 04:09 Just plugging away on Gantt, actually. We're making some real good progress with Gantt for Rindle, which is pretty exciting. We have some really early demos of it, I know you've seen it, you haven't gotten to actually fool around with it, yet. But I know you've seen like a demo of it and I think it's coming along pretty nicely.

Brian: 04:33 Yeah, I'm pretty pumped, I think this is probably one of the most requested features from our customer base, and potential customers that we've talked to. And I'm really excited about it because I've used them before, I think they have great use-cases. I think it's also gonna make for some great podcast episodes, too, because there's definitely opinions on Gantt and how to use them, how best to use them, how can you use them with [inaudible 00:04:57] or whatever workflow you're using, right? Things like that. So I think there are definitely some interesting things to talk about on that front, but as a planning tool, Gantt is pretty awesome. So it's exciting to bring that to Rindle.

Tom: 05:11 Absolutely.

Brian: 05:12 Great, so before we get started, if you have questions, topics, or team scenarios you want us to talk about, tear down, you can call us and leave a voicemail at 860-577-2293 or email us at workflow@rindle.com.

Tom: 05:27 And please also don't forget to leave a review.

Brian: 05:31 Alright, so onto the main topic. So we're talking about documentation today. I think we're definitely pretty passionate about this in a lot of ways because we've had experiences, some good, some really bad. We definitely have an opinion on how things should be documented, at least how we do it. So, Tom I don't know how you feel about this, but I especially am passionate about it because I've had to create 70 page specification documentation and all kinds of crazy stuff, down to the easy simple stuff. So it's kind of been a nightmare in my career.

Tom: 06:11 Yeah I think that this has a been a constant point of frustration, even with us at Rindle, we have gone through several iterations of documentation, as we're about to talk about. And I think finally, you know, several years later we've finally come up with something that we feel is a pretty good means of documenting new features.

Brian: 06:39 Yeah I think we've even taken it from doing no documentation, right, saying like, "Well, we don't need to do documentation. We don't need to write anything down or do anything like that. We can just go.", right? 'Cause we're completely collaborative and this is how we're gonna work and we don't wanna waste time on documentation. But it turns out that, you know, we have come to a probably happy medium, which is cool.

Tom: 07:00 Yeah, absolutely. So heres where we stand on documentation. We feel as though people are generally turned off by documentation. It takes a lot of time, it takes a lot of money, and people feel as though it's time that they're not doing other work, or not doing any work in some scenarios. Honestly, after not documenting for various features, that mindset is pretty much a recipe for disaster.

Brian: 07:27 Yeah, I think, especially depending on your scenario you could be like us and you're working internally with a team or maybe you do have other stakeholders and clients and other things like that. But I've always experienced on the client side, too, where the clients are like, "Wait, you're gonna spend four weeks documenting this project?" But, you know, it's a eight month software development project, right? Or whatever it is. So, they look at it as like, "Whoa, we're gonna waste a month making sure that everything's documented?" And again, those are probably extremes of documentation, but definitely kinda frowned upon from the client's side.

Brian: 08:00 It's sometimes frowned upon internally, from bosses and powers-that-be. Where it's like, "Oh, we're gonna spend all these hours and all this money on documenting something? We should be coding it, we should be creating it, designing it." Whatever it is you're doing. But yeah, I think it is ... that mindset in general is definitely a recipe for disaster, because you're just not doing the necessary leg work to properly plan and understand exactly what you're doing and why.

Tom: 08:29 And if you don't do any documentation, from personal experience I can tell you that the project is going to take longer. And more than likely the first version of it is not gonna be what everyone had in mind, at least all the team members, except for the one person really driving the show.

Brian: 08:49 Yeah it definitely morphs as you actually get it down and however you're doing it, right, and actually get it in front of people. As opposed to just in conversation or in your own head. But yeah, I also found that most people don't like documentation because we all understand generally that 9 times out of 10 it is actually gonna be wasteful, even though you think you're doing it for a great purpose. Because either you overdo it, which I've done myself and I've had to do it for my job, right?

Brian: 09:18 Where you have to create this 70 page functional specification document that takes hours and possibly weeks to create. And you know that you're putting way too much detail in there, which I ended up doing and in hindsight was crazy, how we were trying to like spec out what we were building. And this was software development at the time, and basically you end up instantly, the second you create it, it's basically stale. Like you know at the end of it, it's like, "Okay, look at this, sign off on it, and we're gonna start, and the second we do that this is gonna be outdated."

Tom: 09:57 Yeah, because as soon as the developers, the designers, actually start to get in there, especially if this is documentation created by someone with less technical knowledge, or even knowledge of how all the pieces are actually gonna fit together, things are gonna change. And then documentation is useless, more or less. Basically just as quickly as you wrote it, it is useless.

Brian: 10:27 Yeah, so from our perspective, that's kinda how we feel about why documentation has a bad rap. We definitely have a more agile mindset when it comes to documentation. So if you have any sort of team environment, we are basically of the opinion that yes, documentation is definitely needed. But, that documentation should be minimum and I always like to think of it like an MVP, you know, a minimum viable product. Minimum viable documentation. It should be exactly what you need in order to move forward and create, right? And I think 9 times out of 10, like we're saying, it actually gets way too complicated and that's when it gets out of hand. If you think a little more lean, a little more agile, and think simple it's much more useful.

Tom: 11:13 So yeah, basically our opinion is that you should not be wasting time documenting. You shouldn't be wasting time like formatting some document and making it all pretty to present to anyone. It should be a bare minimum document with, as you'll see, it should really be functional, like business requirements more or less. But we'll get into the nitty gritty of that in a little bit.

Brian: 11:37 And again, like what we were saying with the examples before is that the more time you spend making a pretty formatting, all the things that go into that, it is stale the second that you complete it. So you can spend hours and hours and weeks and week and tons of effort, nights and weekends, whatever that it takes to get the document done, and really you're doing all that work possibly for, you know, instant stale document that you have to then deal with, right? So why not do it quicker and get moving quicker, 'cause things are gonna change anyway. I also find that the longer and more complex it is, the harder it is for people to understand.

Brian: 12:16 So again those 70 page documents I used to create? I put that in front of a client, I had to go through page by page and explain it and they still wouldn't fully understand what we're talking about. So we had to go over it, over it, you know, crazy. Like there were wire frames in there, there was details about how things would function and it was just craziness. So, in the end, they didn't even fully understand it and then I'm trying to get them to sign off on something and saying, "Yes, this whole 70 page document, by the way, it's like a contract, you're signing off on it and we're gonna seal this up." You know? So to explain that and then to feel comfortable with it was really complicated with that big of a document.

Tom: 12:54 Alright, so with that said, this is how we think about documentation nowadays. This is again through a lot of trial and error, and what we have ultimately arrived upon. So first we have ... we define this as requirements.

Brian: 13:12 Yeah.

Tom: 13:12 So think of it like a for dummies book or like an introductory class, like a 101 class if you will. You're making statements that everyone can understand about what the business requirements are. You're explaining the business goals and the outcomes. Think about this kind of like, if you know anything in [inaudible 00:13:38] world, it's like user story, it's like as a user I should be doing, or I should be able to do this. And at the end of the business requirements you should get everyone on the same page about what ultimately this thing that you're creating is going to do at the end. And that's really the end goal, that you're not getting into real technical details yet, you're not ... you're basically just like, "Hey, at the end of this project, this is exactly what I expect this piece of functionality to do, from a very, very high level."

Brian: 14:17 Yeah, and we even struggle with this, 'cause we tend to get into more technical conversation, or even design conversation for us, right, 'cause we're building software. So it tends to kind of bleed into the conversation, we gotta always say, "No, let's not talk about that right now. We're just talking about the business goals at this point, the business requirements." What is it gonna do and for what reason? So, really it's plain English. It should be something that we'd start with, for sure, because we don't wanna get into those technical details yet, but at the end of it, like you said, it should get everybody on the same page as to, "This is what it's gonna do and why."

Brian: 14:53 And then from there, we move on to something a little more technical, but the functional requirements. So, that's basically "How are you gonna do it?", right? So we talked about what we're gonna do, but now how're we gonna do it? These are basically the blueprints for implementation, or things we're gonna need to actually go ahead and execute this. And this sometimes does require additional artifacts, in addition to just the business requirements, we are creating other things, maybe it's data structure in our example, data collections if we need other information to collect for whatever reason. And a lot of times we do sketches or mock ups, right, for design purposes.

Brian: 15:31 Just to be like, "Yeah, this is the general concept, are we all in agreement?" So we get into a little more detail now and for you, Tom, I know sometimes it gets into like again, those data structures, maybe it's API calls, maybe it's other stuff that you need to actually think about a little bit and explain to other people who are working on the project to actually move forward with it.

Tom: 15:50 Yeah, absolutely. I do like to think about this more as this is logic, if you will, in terms of a programming type project. These are like the business logic things, the unique things that if you're trying to code this you might not really realize from just reading those business requirements. So, yeah, again not a lot of detail, and the one key thing about this is you kinda want it to be as complete as possible without really having dove into the actual nitty gritty of, "Okay, this is what we're gonna use for this." You really don't wanna go there, you just kinda wanna be like, "Okay, yeah we are not gonna let them edit this thing.", right? They can only create, they can only delete. That's a very specific thing, but important to note.

Brian: 16:52 Yeah, I think another example is, even for the conditional automations we were planning out, you know, we have an automation platform, we're adding conditionals, so we started to plan that out a little bit. And we had to create a spreadsheet, you know, because all these scenarios that we had to talk about, of like, "Well, what are we gonna offer and why?", right? And there's a list of things that will happen if you select a certain option, then another set of options appear based on that. So it's just more complicated, you can't just put it into a bullet on a spreadsheet, or whatever.

Tom: 17:23 Sure.

Brian: 17:23 It had to be a little more detailed, and it had to be done, because there's no way we can have meaningful conversations and not have something to reference that was thought out and mapped out. So it's just that extra detail that's missing from the high level business requirement.

Tom: 17:38 Yeah, I think that's really important, there's gonna be some level of artifacts, they could be either quick sketches, a quick mock up, like a wire frame just so you can throw in there so hopefully it clears everything up and it gets everyone on the same page.

Brian: 17:57 Cool. So let's talk about how we actually do our documentation for feature development, so that's primarily what we plan and map out. The first thing we do, is we create a Google Doc, we use Google Docs, we're [inaudible 00:18:11] users. So that's our main go-to. Obviously it's collaborative and all that stuff, so it fits right in. We name it as a feature, obviously, so if something like conditional for automation, that's what we name it. And we really keep the formatting very simple. We don't get, you know, we might add a title [inaudible 00:18:29]. But we're really just using bullets and just bulleting things out. Not getting crazy and kind of doing complicated layouts or anything like that. We're really doing a subheading of business requirements, you know, bulleting those out and taking the time then to brainstorm and worry less about formatting and presentation and more about just getting the ideas out into a list.

Tom: 18:51 Awesome, yeah. And then once we have those business requirements written down, that makes sense to everyone that's creating it. We move on to creating any functional requirements that are necessary, and again reiterating what we said before, like this is really where you might get some artifacts or sketch some mock ups, simple wire frames, just enough to everyone on the same page and agree on a direction. It'll definitely probably end up different once you actually get into the creation of it, again it's not really worth spending a ton of time on this, you just are trying to get everyone on the same page.

Brian: 19:33 Yeah and usually we start with kinda the same process of like, okay let's start talking about the functional stuff and let's start bulleting stuff out, right? Just to get some of the ... 'cause usually during the business requirements things start to cross our minds, right? And we're already ... and again, we have to stop ourselves from really getting into that conversation. So we kinda like dump it out right away, 'cause I remember the last time, Tom, you were like, "Oh, wait let me get these couple things written down really quick, 'cause I was thinking about them while we were talking about the business requirements." And then from there we can decide, "Okay, you know what, we probably do need a mock up. We do need a wire frame of something to show how this works, to make sure that we're on the same page.", or, "We do need that Excel spreadsheet for conditionals.", right, for automation. We do need to have a reference, and it is complicated, and it's a lot of information to kinda get together. So at that point we actually decide, minimally, what we need to pull together. We don't have a templated thing that we follow every time, because not every feature, every project that we work on, needs the same set of things.

Tom: 20:34 Yeah.

Brian: 20:34 We're not always gonna do a wire frame, because maybe we're doing a feature enhancement, and the design is pretty much done. I also think that comes into play with some processes, right, we lay out process. Like we should do this every time. Well, we should do it if we should, you know, if we have to. If it makes sense. We shouldn't do it if it doesn't make sense, 'cause you're wasting time and just creating stuff to create it.

Tom: 20:56 Absolutely. It's important to do it then, like typically at this point ... the actual business stuff is more or less done, right? And then we typically ... the people that are trying to define those high level business requirements and the functional requirements, kind of then get other team members involved at this point. So at this point we talk to the developers in our scenario and we try to get some more technical specifications jotted down. And this sometimes requires research and a couple days to look into what's the easiest way to do this, or what's the best way to do this, right? Or what are the pros and cons of doing this quick and easy, versus like a more elegant solution? And we'll come up with naming conventions, we'll come up with API calls, and cut them down. But again, pretty high level, like you're not gonna write down every single thing, I mean we have means of documenting the API once the API is done, more automatically. We don't need to have formal documentation for that.

Brian: 22:13 Yeah it should be high level enough to get everybody in the direction, and once you get into it, as we all know with any kind of project, things will change. As you research, as you learn, as you implement, and things don't work as you thought they were. So that's where you gotta kinda figure out where's the best stopping point. Do we know enough to get started at this point without people being confused? And try to prevent yourself from going down a rabbit hole and trying to map out everything, and that usually leads into frustration, more discussions that last forever, right, 'cause you're just complicating a discussion. And a lot of times, too, when you don't see something you'll go in a rabbit hole and talk about something, and you don't see it. So let's say it's the design, or even a Excel document for the conditionals. If you don't see in front of you, it's really hard to keep a conversation going. Because you get lost in your own thoughts, right? And you're like, "What are we talking about again? Wait a minute, I'm confused."

Tom: 23:10 Yeah.

Brian: 23:10 So, the high level piece, if everybody agrees kind of to go forward at that point, then you should go forward and start implementing. And then of course you can update and modify from there as you go, and make changes. But this way you don't waste any additional time if you don't have to.

Tom: 23:27 Yeah, that's a really good point. We also have paused after establishing these initial requirements, and someone has taken some time or multiple people have taken time to create some rudimentary wire frames and bring them back so we actually all can get on the same page. Usually these are quickly done, like either through a Photoshop type program or by hand, right? And we share them with each other, we have a little more discussion about it, and then we're kind of good to go. We like to get into the environment that we're actually creating in as quickly as possible. Like creating that end product as quickly as possibly. But, we don't wanna get there too quick. We don't wanna get there without actually establishing what needs to be done.

Brian: 24:20 Yeah, it also gives you a point of reference, too, when things do go off track, or you have questions about, "Well, why are we doing this, wait a minute, I thought it was supposed to be this way?" You have at least some point of reference to go back to and say, "Okay, well actually this is what we discussed originally." And you have kinda something that we all agreed on in the beginning, as opposed to just going and everybody kinda changes rules as they go potentially, right?

Tom: 24:41 Yeah.

Brian: 24:42 So it's better to have something in place, simple again, simple and easy, but something that we can all refer back to and say, "Yeah, okay we did say this. Oh, yeah I remember why, okay let's squash this and move on."

Tom: 24:53 But, and we're saying a lot of buts here, everything that's written down in this document is not set in stone.

Brian: 25:01 Sure.

Tom: 25:01 Like you might come back to this document and remove some of these things because they're out of the scope of the timeframe that you have to get this particular feature done, right? So you might circle back around to them. But it's good to basically jot everything down and then come back and remove stuff and tweak stuff later, then again, doing everything up front.

Brian: 25:26 So this episode was a little longer than we thought, so we ended up splitting it in two episodes, part one and part two. So stay tuned next week for part two.

Tom: 25:36 Well, I think that about wraps us up for the day. If you have a question for us you can call into our voicemail number at 860-577-2293, or you can email it to us at workflow@rindle.com. Our theme music is an excerpt from Thunder Rock by Magic Studio, used under creative comments. Subscribe to us on iTunes by searching for Workflow and visit rindle.com/workflow-podcast for a full transcript of each episode. Thanks for listening and we'll see you next time.