Home
Episode Twenty

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

Nov 21, 2018
Also available on:

Show Notes

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

00:41   Intro
01:07   How does Rindle document feature development? continued from Episode 19
05:23   Documentation for clients
15:59    Documenting rush projects
20:16    Tips for taking action!

Full Transcription

Brian: 00:00 This is Workflow, episode 20.

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

Brian: 00:28 Hey everyone, I'm Brian, and I'm one of 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. And this is part two.

Brian: 00:41 Alright guys, I just wanted to hop in here and do a quick intro. I'm flying solo today without Tom, but wanted to let everybody know, if you're looking for part one of this, it's episode 19, and this is episode 20, part two. We had a long recording session, had a lot to say about documentation, so it ended up being quite long, and we felt it'd be better to divvy it up into two episodes. So, without further adieu, here's part two.

Brian: 01:07 Awesome, so, from there, once we have all of those, like you said, we said a lot of buts, but we have all those things worked out, where we've included the team, we've gotten some of those artifacts together, we feel like this is in a good spot as far as a plan of attack, then we generally create that ... those business requirements, we basically turn those into tasks on our roadmap. So we typically have something already on a roadmap, because we are developing and planning features all the time, so we have a roadmap where we have a list of priorities there. So there's usually a task already there for the feature. And then we'll go and add those business requirements as sub-tasks in that task.

Brian: 01:48 So we basically document in Rindle now, our project management software, hey, this si what we've agreed on, we also attach the Google doc to that task, to that feature task. So now we have a place that lives in a collaborative environment where the features on the roadmap, the plan is there in place, we actually have tasks in place of what needs to be done from a business requirement level, and then we have the document there for everybody to reference, if we need to go back to it. So everything's organized, nice and neat, in one place.

Tom: 02:19 Yeah, and now, at this point, any further discussion about this, and any updates, they go in the task, not in the Google doc. We typically then ... unless it's a change to one of the actual documented features, we typically switch it directly over to, in our case, Rindle.

Brian: 02:43 Yeah, I mean, if something like you said, sometimes those requirements change, you say, oh, we don't need to do this anymore. You might want to update that Google document just so there's no confusion later, right. But usually when it comes down to the actionable tasks, those are all managed in the task itself, so we're not having double data entry or anything like that, from that point on, all the actionable things are managed in the task itself.

Tom: 03:06 Yeah, and this actually sometimes does make it so the actual end product is not in sync with the original Google doc, but, honestly, that's okay, because the Google doc is not meant to be formal documentation. It's meant to be, let's get everyone on the same page, and here are basically what we're going to do. But again, things change as you get going, which is why really big, 70-page formal specs just don't work. Because they're not going to match up with what the end product is.

Brian: 03:40 As we already mentioned, any documentation gets stale after a period of time, right. But the fact that you spent a limited amount of time on it, you didn't waste a lot of time on it, you did it quickly, so it's okay to let it go stale. It's supposed to go stale. [crosstalk 00:03:53] will go stale no matter what you try to do. That's the real deciding factor is, hey, did you spend four weeks on documentation, or did you spend four days.

Tom: 04:03 Sure.

Brian: 04:04 And now it's like, okay, well, that's gonna die out and become stale, and we've already moved into a living, breathing project at this point. So it served its purpose and we're moving on.

Tom: 04:15 So it's pretty relevant, we literally just the other day went through this process for mapping out [inaudible 00:04:24]. And how long did the entire thing take?

Brian: 04:28 I think we probably brainstormed from start to finish, an hour?

Tom: 04:32 Probably about an hour, and maybe then another quick meeting before we handed ... were able to hand it off to other team members, just to review some extra things that were added probably after that initial meeting.

Brian: 04:49 Yeah, so we're probably in a couple of hours at this point, maybe two, three hours of actual time on the planning. And again, this is something that we're starting to consider working on at this point, where once we're all in agreement, we will start some work towards it. But right now, it's not being developed at this point, we're still finishing up some other things that are happening right now. So it's a great time to get ahead of it, we plan, we get a few other people involved, we collaborate at this high level, and then we move on. It is a perfect scenario, it's exactly what we're doing right now.

Tom: 05:23 Awesome. So that pretty much does it for our process. But what about documenting for client projects?

Brian: 05:32 You mean documentation for client projects?

Tom: 05:34 Yeah, how about that? We'll go with that. How about documentation for client projects, Brian?

Brian: 05:41 Yeah, I think this is the other side of the coin, which, our scenario, obviously, we're a software company, we're building software and features, we don't have a lot of external stakeholders outside of our customers. But most of those stakeholders are internal. If you're in ... we used to work at an agency, anything that has client-facing stakeholders or anything like that, you're typically ... if you have to do what I used to have to do and create functional specifications, they are presented to the client.

Brian: 06:12 So, they're normally part of some kind of client sign-off, which I mentioned, it's almost like a contract. So there's a proposal usually, and they talk about pricing, and then there's whole specification that gets put together, and this is actually what we're going to build now, make sure you sign off on it, because it's also going to be used to control the scope of the project, right. And expectations should all be set here, and we should all be on the same page at the moment this is signed off on.

Brian: 06:43 So I think these kinds of documents, this is a 70-page document that I was referring to this whole time, and I've literally created that ... probably bigger ones, actually, I think I did over a 100-page one one time, which is absolutely craziness. But these are so time-consuming. The amount of detail we were doing in these ... in order to get it to a point where somebody actually signs off on it, like the client, and says, yes, that is exactly what I had in my mind, you have to get into detail at that point, right. Because if you're really trying to seal up all that into a nice package, you have to get a lot of detail.

Brian: 07:16 And we were trying ... and Tom, you and I worked on some of these together, we're trying to predict the future at this point. We're trying to predict, this is the best way to go about this, and we're going to explain it to you exactly how it's going to look, through wire frames and other design concepts, and this is what we're going to produce for you, basically, without anybody doing any work at this point, right, as far as software development, right, which is what we were doing.

Tom: 07:41 And just to set the stage here, this is basically all based around a discussion you've had with the client, where they've kind of explained their wants and their needs, for this, whatever you're creating, this app that you're creating for them. And 90% of the time, it's completely unique to that client, so it's not like you can even just base this off anything.

Tom: 08:05 It's not equivalent to architecture, or engineering, where okay, we're going to map out blueprints of everything, right, because we're building a bridge, right. We're building an app, but this app is completely different than that app, right. It's not the same.

Brian: 08:27 And we even tried at one point, in the agency we were at, where it was attempted to kind of templatize functional specifications, which you can to some point, like some information will definitely be standard in there, for whatever reasons, especially for different types of projects. But we were building, at the time, very custom projects, like you're saying, so it wasn't like where we could just spend a day on it and whip up a functional spec, right, it was actually very, very custom.

Brian: 08:55 And we had discovery meetings with the customer, where we spent hours talking about, well, what is the vision here, what are you trying to accomplish, what are the goals, what are the pain points, so we can try to basically be a software dev team for this customer.

Brian: 09:07 And basically, if you're trying to create that kind of document, what you're basically trying to say is that, you already have all the answers to all the problems that are going to happen in the future, present day, and you have all the solutions to all the problems that you're going to run into, unexpected things, all of these things, right. That's what you're basically saying by saying, hey, i can create a 100-page document for you right now, and we're going to sign on the dotted line and go to work.

Brian: 09:34 Which is just not reality, which is why it's so ... it's not the best idea to go down that route if you don't have to. I've been through this, it's painful, tons of hours, and it's failed us more than half the time.

Tom: 09:48 So, why has it failed? The document gets outdated. We've been over that before. Basically, the underlying problem is that this is also trying to serve as a contract, right? This is exactly what we're going to deliver so we don't get screwed on the amount that the client is paying us to do this.

Tom: 10:12 So instead of actually solving that problem, we're trying to put all this work in ahead of time that most times the client isn't even paying for. Sometimes clients pay for discovery, but nine times out of 10, they don't. So you're putting all this effort in, trying to basically create the app before you go and create the app, that you don't even know if the client is going to pay for.

Brian: 10:38 Yeah, and it really, really stifles the creative process for something like this, where as a team, actually implementing it, you might be like, this wasn't the best idea, we probably should have thought about doing it this way. But now you're held to this contract, this functional specification document, where you've actually laid out wire frames and maybe even sometimes design concepts.

Brian: 11:01 So you now create all these other problems, that are caused by this contract, because you have no leeway. And if you do, now you have to get into change orders, and complicated discussions about why we're not going to do what they originally thought we are ... what we were going to do, and why we're going to do something different.

Tom: 11:17 Or, more often than not, you end up just doing it, and not getting paid for it.

Brian: 11:21 Right, yeah, and that could be the case as well, which we've discussed on previous episodes as well. But in the end, if i were to do this all over again ... and even in the position I had right before starting Rindle with you, I was doing pretty intense functional specifications. Now, kind of hindsight, looking at that, I would focus on solid but simple business requirements, and solid acceptance criteria.

Brian: 11:50 So not only the business requirements, but because you have a client-facing stakeholder in this scenario, acceptance criteria. And this comes again from the agile world. So, yes, what is the business requirement, but when we implement that business requirement, we solve that problem or solution, what it is going to be ... what are the things that have to be there to be accepted by the client.

Brian: 12:11 And this goes into, even previous discussions we've had about, this gets in a little more detail, so if you're creating, again, that job submission form, it's very simple to say, yes, a user can go to the page, fill out the form, submit it, and a PDF of their resume comes to you in an email. Right? That is great acceptance criteria, because now you have a solid use case, you have the acceptance criteria, and no matter how you go about making that happen, doesn't matter to the customer, because the customer in the end is going to get exactly what they expected.

Brian: 12:42 So you can choose to do a different type of form, you can choose to send the email a different way, to package the PDF a different way, whatever you want to do creatively, or functionally-

Tom: 12:52 It puts all the creative back in your court, as opposed to ... the creative is eliminated if you have this 70-page document explaining exactly how every single feature's going to work, what color the button up in the corner's gonna be-

Brian: 13:07 And that's a great way to put it, it puts it back in your corner, and I think that's a mistake of the past, and I think a lot of people are moving away from that these days. But taking control back of that process, of that's why they're hiring you, because you're experts in this area, let's leave that to us. And we'll figure that out.

Brian: 13:28 If you can create that accurate set of requirements, with that acceptance criteria, that could be a very simple document, you can still make it look pretty, but now you're not talking about a 70 or a 100-page document, you're talking about maybe a two-page document that everybody can get on board with, and you can even pitch it to your client saying, hey, we just saved you a bunch of money because we didn't spend four weeks planning this out. We kept it very lean, and we're going to go ahead and deliver this criteria to you, and we're going to do it in the best way fashion that's suitable for the creative team or development team, or whoever's doing it.

Brian: 14:00 So, hindsight, it's always 20/20, but that's how I would approach it today, if I went back to that world and had to put this together with client-facing assets.

Tom: 14:12 I think the only other thing that I would do if ... well, not only if i were to do it all over again, but if I owned an agency, is I would really have a very narrow set of offerings. Like, we only do iOS development, or we only do web development, but this type of web development. Very specific, because as soon as you get into these unknown areas, like as soon as you say yes to something that you don't really know a lot about that, that's when you start to run into a lot of issues with not being able to properly scope things out.

Brian: 14:52 Yeah, that would keep any kind of process like that easier, because you can almost start to templatize it a little bit, right, where you're dealing with a lot of the similar problems over and over again. So I agree, I think definitely ... at the time we were doing things, we were really doing custom stuff, so we were solving various problems for various reasons for various people. (laughs)

Brian: 15:17 So there was no real focus, so it's very hard to kind of hone in on a simple set of stuff that you can kind of use over and over again.

Tom: 15:27 Yeah, absolutely.

Brian: 15:29 But, take this with a grain of salt, too, because obviously, we realize that this may not be possible, and sometimes you just have to bite the bullet ad you have to create the 70-page document like I had to do. But this may be something you can keep in the back of your mind and hey, maybe we can work towards this. Maybe we can make some movements towards it, as opposed to changing the whole process. But I think when it comes down to it, thinking about how much time it saves on upfront work that is stale and all those things, the benefit is pretty huge.

Tom: 15:59 So last real question that we have to ask here is, what if it's a rush and you have absolutely no time to document?

Brian: 16:09 I think, well, especially in the agency world we came from, this happens all the time, even in our world today, sometimes we have to do things really quickly, right, and we don't have time to spend, and we don't have the freedom to be like, hey, let's spend a week brainstorming this, for whatever reason.

Brian: 16:24 I think keeping the documentation simple as we discussed will organically help this problem, right, because you're not being like, wow, you want a rush project in a month and you expect me to create a functional spec, and I've been in those scenarios where I'm literally trying to cram a functional spec into like, two days, and I'm working endless hours and burnout and all these things come into play.

Brian: 16:47 So I think you could probably do it in a few hours for a rush project, as opposed to taking weeks and weeks, if you keep the documentation simple, as we're talking about today.

Tom: 16:56 Awesome. I think you can also, or you basically have to, rely more on status meetings. And in keeping the client as up to date with the progress as possible.

Brian: 17:09 Yeah, and that could mean meeting every day with the team, every week with the team, depending on how long that rush project is, defining the work as you go, in your stand-ups or whatever meeting cadence you have. It's not going to be something that's going to be all thought up upfront, with user stories and all the things we're talking about, you kind of have to go on-demand, maybe work that out with the stakeholders as you're going.

Brian: 17:31 And then like you said, meeting with the client, keeping them up to date, that could be every two weeks, if it's a couple month project, or a month project, or whatever it might be. And being right with the client, and showing work in process, because you don't have any other documentation, right. So to get that work in process in front of them as quickly as possible, that's going to drive what work you're going to communicate to the team in your stand-ups, right, and how things are shifting and changing and moving.

Brian: 17:58 So sometimes, actually, I've found that the rush jobs, when we didn't have time to actually do documentation in our world, before, when we were doing all this crazy documentation, was actually fun, because we were doing it more agile and narrative, right, which is kind of what we wanted to move to at the time, so it kind of forced us, forced our hand a little bit, to be like, well, we can't actually do what we normally do here, so let's just go at it and figure it out. (laughs)

Tom: 18:22 Honestly, if it's truly a rush job, and you have some hard deadline that ... there's some event coming up that this website or this app has to be launched by that event, right ... the expectation should be set that, hey, the client might not have as much say in the nitty-gritty of this, we're shooting for the deadlines. So, we're going to make something awesome, we're going to make something pretty, but you need to set those expectations early that all of their dreams aren't necessarily going to be met, and you're going to try to do the best job you possibly can in the tight timeframe.

Brian: 19:03 Yeah, and it may not even be the normal process, right. Especially with an existing customer, and they're kind of used to how you do things, hey, this is a rush, this isn't going to be the normal process, you're not going to get the same treatment, or artifacts, and all the other stuff that we normally do, this is how it's going to run.

Brian: 19:22 So not only the end result ... which we, Tom, as we know, had to do many times ... where, hey, yeah, this is your pipe dream, but in reality, we can give you this. And that's just what we can do in four weeks. But also, you're not going to have a requirements meeting, you're not going to have functional spec documents, or crazy wire frames, and all design concepts, we're just going to kind of give you what we need to give you to get it done, right.

Brian: 19:46 So, again, showing the client as we go, and iterating, made a lot of sense, because we can get the design concept, we'd only probably show one in that case, in front of them in a couple days, right. So we can get their feedback, get any changes that need to happen ... minimal changes, and get it going, as opposed to what we'd normally spend a week, or two weeks, designing concepts out, right, and presenting them with three or four concepts. So, yeah, setting those expectations in a rush scenario will make your life easier regardless.

Tom: 20:16 They sure will. Awesome. So, let's get into some tips for taking action.

Brian: 20:21 Yeah, I think the tips are throughout the whole entire episode, we've kind of been going over them. But I think the main message here is simplify your documentation, weed out hours of work that don't matter, whether that be hours of needless detail, or design, making things pretty, whatever it is, think less formally, and a little more scrappy, and of course, when you need to make things look pretty, make 'em look pretty, but think a little more lean.

Brian: 20:50 If you can't do it right away, make all these changes that we're talking about, because sometimes you get excited, like, yeah, let's do this, and it's kind of hard to make change. So, can you work towards it, can you make small steps towards it, can you take one part of your process and make it a little more scrappy, a little more lean, and not make it so formal. So you can give it a try with that.

Tom: 21:11 Yeah. And finally, I think the last tip is to keep the artifacts really simple, right. You don't want to spend all this time basically creating the entire deliverable in some sort of mock-up wire frame program, right, with all the bells and whistles of what the final product's gonna be. That could take a tremendous amount of time, and it's not worth it. Keep it nice and simple, hand-drawn things ... not necessarily hand-drawn, but simple sketches in some sort of design program ... Excel document with this is the flow of logic, if you will, if it's some complicated logic. Simple, quick and easy.

Brian: 22:04 Yeah, I like to use the example of, when I think about it, I think about, well, what do writers do when they write an e-book, or write a blog post, right. Usually it starts with an outline, and an outline is like the simplest form of brainstorming, right. Just get your ideas out, get them organized, and if you can think about your documentation as as simple as that, I think that's a great place to start.

Brian: 22:25 Because what you're creating should happen in the creation part, not the documentation part. You should be able to get simple things out on paper, but it's not like the writer's creating an outline and writing paragraphs in the outline, right. It's just short ideas to get their gist apart, and the creative process and the fleshing out of that will happen later.

Brian: 22:46 So if you think about it that way, I like to think about that when we're doing ours, because we're going to keep them simple, we're going to keep them simple bullets, we're not going to get into complicated discussions and writing tons of stuff out that nobody's going to read. Short bullets, short user stories that are meaningful and useful, and not a whole bunch of ... that's another thing, a point we never really talked about, but it's just the fact that when you create big things, or long pieces of text and all this stuff, people don't read it. (laughs)

Brian: 23:14 You could have tons of details in this masterful paragraph that's half a page long, and somebody then says, well, I didn't know that we were doing blah, blah, blah. Oh yeah, it's right in this paragraph, like that person ever read it, right. Or they could even find what they're looking for. So an outline is a great way to approach it.

Tom: 23:29 Yeah, I mean, I do that every single week when we record this podcast.

Brian: 23:33 Yeah, exactly, yes, you do, Tom.

Tom: 23:36 (laughs) Alright. Awesome.

Brian: 23:37 And the other point is, keep them organized. This is something very simple, but you go to the effort of creating these artifacts, even though you're hopefully doing it the simple way, but make sure that everybody can get to them, and they don't have to go searching for them, or there's this one piece kind of floating out. This frustrates me the most, when somebody doesn't attach a Google doc or something to the task, right, and now I have two documents there that I need, but the third one, I had to go find, right.

Brian: 24:02 So everything should be nicely packaged so the team or whoever's working on it has everything they need as they work and go, and there's no confusion.

Tom: 24:10 Yeah, absolutely. Just because you're not doing super formal stuff doesn't mean you should slack off on keeping stuff organized. I think that's really key.

Brian: 24:21 Well, I think that about wraps us up for the day. If you have a question for us, you can call it into our voicemail number at 860-577-2293. Or you can email it to us at workflow@rindle.com.

Brian: 24:33 Our theme music is an excerpt from Thunder Rock by MagikStudio, used under Creative Commons. Subscribe to us on iTunes by searching for Workflow, and visitrindle.com/workflow-podcast for a full transcript of each episode. Thanks for listening and we'll see you next time.