Documentation for developers: A gift to your future self

But thank you first of all to the midcamp team for inviting me to speak. And thank all of you for starting your day with me this morning. I'm excited to be here. This is my first in-person mid camp. I was able to kind of attend the year that Covid got it, um, kind of flipped to a free event and we were all remote so had a chance to attend. But this is my first time actually coming in person. It's been really great so far. Uh, so I'm excited to speak today about documentation for developers. I've been working for about nine years now in my career, and have been thinking a lot about when I first started my career, and now thinking about developers coming into my team and getting started, and just kind of realizing that there's a lot to learn and how documentation can help along with that process. So I started back in 2015 as Drupal seven was kind of alive and well after having a little bit of freelance WordPress experience. And I remember as I was getting started, a coworker showing me this graph that might be familiar to some of you.

It shows the learning curve for popular CMS platforms, and kind of shows that Drupal can be a little bit treacherous, especially in the beginning. And so I was just kind of my first impression of Drupal and coming into it with that WordPress experience, which is a nice smaller curve there and just trying to figure out that, oh, okay, this is a little bit of a different beast here. So I started learning about, you know, the various kind of Drupal, uh, core term's content types, nodes and fields, taxonomies, user roles and permissions, modules, and of course, views. But then at the same time, this being my first real job as a front end developer, I was also learning a lot about front end best practices like CSS processors, semantic HTML accessibility, version control, atomic design. And I was in my first job as a consultant at an agency. So I was keeping in mind things like customer service, managing tasks across multiple projects, understanding project requirements and goals, fighting against scope creep, and ideally keeping work life balance in mind.

So when you put all those things together at once, trying to learn everything as fast as you can and as much as you can, it can feel a little bit like you're in a boat fighting against a tidal wave. Needless to say, there's a lot to learn and it can quickly feel overwhelming to a new developer. That's definitely how I felt when I first got started. And so the tendency I think, I think the tendency that I had was that I really wanted to dig deep into the code and really get my skills down and become as good of a developer by writing code as I could. But then I kind of realized, as I was getting deeper into my experience, that there were other ways I could also become a more effective team member as well, not just the code side of things. So I work at Gravity Works Design and Development. We are a remote company headquartered in Lansing, Michigan, where I'm at. We focus on websites and mobile apps, mostly in Drupal, but a little bit of WordPress and other CMS work as well. And one thing I've always liked about gravity works, where I've been for just about nine years now, is that we hire from a number of different backgrounds, not just computer science.

We have some computer science grads, but I, for example, have an arts and humanities degree with a French minor, and I did some trombone jazz trombone performance in college. So not exactly the traditional pathway into tech that many people might have. So we've also hired people who are HR staff, who have been in customer service, who are teachers, and just see that those different pathways into tech have really helped them in different, sometimes unexpected ways. And so as part of my own college curriculum and just some of my general interests, I had kind of developed an interest in writing. So while in college at Michigan State, my first job was at the Writing Center, where I was both a website coordinator working on their websites, but also a writing consultant. And in those in that consultant position, I would work one on one with students who would bring their writing in, and we would review their work and really help them try to become better writers. So it was the website stuff at the Writing Center, but also kind of working with students on writing as well.

I also freelanced a bit while just kind of figuring out what I was going to do after graduation, figuring out what options were open to me, and so I would do some web development work. But I also did some writing, including for Billboard, like this article that I had written on data I analyzed for special guests who were invited to perform with Taylor Swift on tour and analyze that data and wrote about it. And so I had that kind of writing interest and experience, and I brought that interest in writing and what became really documentation over to Gravity Works as I started my career and kind of came to the realization that documentation could help me in the moment on projects, it could help who I call sometimes future hurt, trying to do support work, maintaining projects, or bringing work from one project into the next, and then also help the rest of my team that was growing as well. Since I started at Gravity Works, I've had the privilege of hiring 18 other front end developers over the years, including several who, like me, started their careers at Gravity Works as developers.

And so I really tried hard to make sure that documentation has remained an important part of our team culture and just really kind of tried to keep that alive. So in this session I'm going to talk through a few different sections, almost as if we're working through the kind of life cycle of a project from start to finish. So first is the kind of preparing and planning stage in the early stages of a project before you're really doing much coding, just kind of getting in and understanding requirements and meeting with the client, then managing what I call the messy middle. We'll talk about that a little bit, then unlocking future potential with your documentation. Talk a little bit about AI and some other tools. And then we'll close a little bit by talking about the word efficient and how effectiveness might be a better goal and how documentation can aid in that process. So on the screen now is a ten digit number. Take a few seconds to review it, and without writing it down, try to commit it to memory.

I won't exactly quiz you, but we'll bring this back up in a few minutes. So just take a few moments and see if you can commit it to memory. It's one of the key points I want to make is that your memory is an unreliable narrator. My work as a consultant means I'm often juggling multiple projects, multiple priorities, dealing with potentially a client fire that comes in and causes some unexpected issues, and just trying to juggle all those things at once. So when we're trying to move quickly and do more with less, do as much as we can. We tend to avoid practices like documentation, assuming that we can just remember it all or keep it in our head, and we'll be able to recall it when I need it. And often I found most of my own chagrin that it's not really the case. And so documentation helps you to offload that from your memory. You don't have to remember it all, and that keeps you productive and focused on the things that your brain really should be thinking about. Those hard problems, those kind of difficult things that are new to us that we're trying to solve.

That's where we really want our brains to be focused, not on just having to keep the things that we need to remember in our memory. And so these next few slides, we'll talk a little bit about some considerations to document in those early planning stages of a project. Starting with component planning, we build with component based design in mind, so our developers and our designers will work together to break down components and name them and put them into a plan, and then build them out in a component library tool like Storybook. So atomic Design breaks down a mockup into smaller pieces like atoms, molecules and organisms going from small to large. And so we'll document our components in that same way, usually using a template like a Google sheet here that you see on the right. And so in that image you'll kind of see a few different atoms and molecules for our project that we worked on with their names and their variants named there. And you might also get some screenshots here as well.

Sometimes we like to use memorable names for those components. Think about things like a hero or a sidekick, and that helps us just kind of build a shared language among our teams about what components we're building and what they should actually be doing. And we'll talk a little bit more about how naming things is hard, but remembering unique names like a sidekick, what exactly is that? Remembering that is harder if you don't have additional context when you first did some planning. So usually in that spreadsheet will include some additional context of what exactly that component means, what it corresponds with, just to provide that context and make it easier for us to get back into it when we've actually moved from planning to execution. So we do the same thing with documenting our content structures, our content model. Usually, like I said, we do a lot of Drupal work, but this kind of technique would apply to any other CMS development as well. And we usually do these in notion, but we've started moving these into a Google Sheets template.

Ours is a little different from this one, but this is actually a screenshot of Acquia's Drupal spec tool, which is out online and open sourced. Um, and that's fairly similar, really. What it does is it breaks down your content structures into things like fields, view modes, image styles, and you're just really planning all that out in a spreadsheet where it's easy to change and adjust. And really, what I think the benefit of that is, is that you're doing early planning early on in the project, while it's still easy to make those changes, but you're also then thinking through and considering how your different content types and other structures are going to connect with and interact with one another. So you get that chance to do that really early.

>>:
In the project. We like to plan our development tasks beforehand as well, whenever we can. And really what I think that does is it helps us get our thoughts in motion early on, and it gives us a chance to just understand what a problem is, and then allow that thought to just gestate in the back of our minds while we might move on and then go do component development next, we don't necessarily get right into the CMS right away, but we have those thoughts and ideas in our mind that are just kind of getting thought through and back in the back of our minds. Right. So with these development tasks, the titles of the tasks, I would recommend making those actionable. So starting with a verb like create or build or add in the title of that task. A couple of examples that I run into that are best to be avoided. One task I had once was called footer. Background is blue, and then I have to look at that and go, is that a request to change it because the mockup says it's blue? Or is that telling me that the website has a blue and I need to adjust it?

And so having to spend time thinking through that is time and energy that I'm wasting, and could be using better thinking through other problems. Another recent example I had was check whether editors can access web form submissions, and then I have to stop and think, are they supposed to be able to access them or not? Do they have access or do I need to get rid of it? And so really, I think tasks should identify a problem, whether it's a business rule that we're needing to solve or a QA issue that's come up that we need to fix, and then the title should be the solution to that problem. So for example, in that example there allow editors to manually reorder the resources list is essentially what we're getting at with that task. In these tasks to feel free to include descriptions, screenshots, any additional context that's helpful to understand and get into the problem. And remember too, that these aren't set in stone. So if you get into the task and you come back later and work through that actual execution of that issue, you can rename your task.

You can update your description just to make sure that if your ID is changed or your plans change, you can keep that task accurate as well. So this is just a more high level overview of tasks on a project. You can see kind of their list of action based titles. And if we were to click into any of these tasks, you might see a little bit more of a description or a screenshot where appropriate, just. To give more context. So key takeaway that I have is that documentation is the act of thinking and then putting those thoughts on paper. When you document while you're doing early planning, you're allowing yourself to be proactive instead of reactive. You're able to anticipate issues while they're smaller and more manageable early in the project, rather than them being urgent at the end. One problem I run into over the years, and I've seen from other developers as well, is that when you don't plan a hand, plan ahead and you don't write things down, you lose track of those plans. Just as the end of the project moves forward and evolves and things happen over time that you just kind of lose that context and those goals.

And then by the time you move from development into a quality assurance phase, you're all of a sudden dealing with issues because you hadn't thought through all the way and you didn't necessarily fit the requirements. And I found that in that QA phase, there often is enough stuff that we need to deal with anyway in terms of like design, QA issues coming from clients as they're getting into the website, just making sure that we've hit all the goals that we need and having to add all of that information of, well, we didn't document this, and now we're having to retrace our steps. It's just a lot of extra work that we don't need to deal with, and already a pretty busy phase of the project. And documentation doesn't have to be this huge, foreboding responsibility. I think that's something I've kind of had the impression of at first, is that this has to be this big diatribe that you write out, and that's what documentation is. I have had that before. I have one example recently where I wrote for a single feature that I built out 12,000 words of documentation about it, and it was one document that I handed off to a client.

And that counts, but also smaller notes, things like comments and commit messages and status updates on tasks. All of those can also be just as important as useful, and I think it's fair to call all of that documentation as well. And by putting those thoughts on paper, what you're doing, like I had said before, is that you're relieving your mind of the responsibility to hold on to them, and then that allows your mind to be spending more time thinking about innovation and problem solving instead. You also free up your mind, and this is something that I have experienced a lot, and I know all of my other developers and my team have always said in the past that it helps them to is that when your mind is freed up like that, you're able to have ideas and solve problems while you're just doing other things, while you're walking the dog, or you're making dinner or, you know, shower thoughts. Um, and, or if you go to bed and you have an issue and you fall asleep and you wake up the next morning and that problem is solved right there because you freed up your mind to think through it in the back of your head, rather than having to keep in mind all the things that you need to do or things that you didn't write down.

So I've been reading some personal knowledge management books lately as well, and thought this quote was relevant. This is from David Allen's Getting Things Done. He says if even if you've already decided on the next step you'll take to resolve a problem, your mind can't let go until and unless you park a reminder in a place it knows you will, without fail, look, it will keep pressuring you about that untaken next step. Usually when you can't do anything about it, which will just add to your stress. And I think that just underlines that point. Well, you know, when you're laying in bed at night and you're thinking about what issues you need to get done and the things you need to be doing, that is just extra stress and work that ideally, if you just write that down, you can get it out of your head and allow yourself to deal with it when you get back to your notes. So we'll talk a little bit more about use cases for documentation in this next section, which is like what I like to call the messy middle.

So the messy middle is the part of the project where your developers are doing work according to the project requirements. They're building out the website that we need, and those requirements inevitably start to shift and change a little bit as your client team starts to get into the website and was really able to interact with a working website for the first time and understand what they can do with, with Drupal and with their website. And so what I found is that documentation practices help to keep that scope clear. It helps keep your plans in motion, and it also ideally keeps your stress lower. So we'll talk a little bit about Miller's Law. Miller's law comes up in user experience and psychology, and Miller states that the immediate memory span of people is limited to approximately seven items, plus or minus two. He did stress that the the magical number seven, as he called it, isn't a hard and fast rule, but it's an average give or take two or so that he would see fairly often in his studies.

And this shows that trying to hold on to a lot of information in your memory is really likely to fail, because your memory span just can't hold on to everything, no matter how hard you might try. So I said I wouldn't quiz you. But just think to yourself about the ten numbers I showed you a few minutes ago. And since then we've talked about several other things. We've introduced several concepts. You've probably got a lot of other thoughts in your brain right now. Do you remember those numbers? Miller's law might suggest that you don't, because there were just too many things you had in your memory. Now, what if I had shown you those numbers in this format? So that's a phone number. And of course it is gravity versus phone number. So feel free to call me in a website. But this practice of breaking these down is called chunking. And these chunks are easier to digest than that big ten digit number. Miller even says that the size of the bits or chunks of information are not as much of the problem as just the number of them that you have to remember.

So remembering just three small chunks there is easier than ten digits all at once. So there are a few different benefits of chunking that can be used when documenting. I think that's true for either tasks or for meeting notes. You want your tasks and your notes to be in small, easily digestible chunks, just in the same way you wouldn't want to read hundreds of words on these slides. You wouldn't want to read a whole book all at once. Instead of having it segmented into chapters for developers, you wouldn't want to look at a giant pull request instead of a few smaller pull requests that have a little bit easier information to digest. In that same way, you wouldn't want to look at a large task that doesn't really give you a good path to start from. One thing I really found that's helped me is that having my tasks chunked in, documented in that way, lets me jump into a project and still be productive, even if I just have a few spare moments, spare moments in between meetings or other work where it's I've taken a break and I've come back and I still have a few minutes before my next meeting starts up.

I can still go into my small chunk task and get something done. And that really lowers cognitive overhead. And that's always good. So that your focus on the work rather than thinking about what we're going to do. I've also found that it helps you more quickly turn your tasks over for review. Um, because they're smaller to test. Just like I was saying with pull requests, they're smaller for those tasks. To test that, you can get them over to QA or to a project manager. Um, and it can also help if you need to reassign or delegate your work. Something I'm trying to do as a team lead when I can. Um, because it's something that's small and manageable. You really want to avoid this kind of draw the owl meme, where you have step one and step two, and there really should be a lot of smaller steps in between that. Um, and if you can't figure out those small steps, that's where you kind of get overwhelmed and unsure of where to go next. So that Owl image is an example of the fog of uncertainty.

By chunking and by having other preparation, we can avoid having similar issues when starting development. If you think about that owl image there, we don't want to look at a mock up and just say, go build the website. We want to think through smaller things. Uncertainty drives procrastination and decreases productivity. And both of those are things we want to avoid if we're trying to be an effective developer. I think this picture just kind of ended up being a nice little metaphor for our project as well. You can kind of note the rocky path and the uneven hill here, and I think that's a good parallel to a typical project that has plenty of known unknowns and unknown unknowns in them to begin with, and we don't want to add to that by not having a clear, well documented plan. So anything we can do to reduce that fog of uncertainty is always good. So these next few slides we'll talk a little bit about documentation strategies in code, in project details and in meeting notes. But one important tip that I learned in my days at the MSU Writing Center, but now also as a consultant at a web agency, was to really know your audience, know who you're writing for.

Is that your fellow developers? Is it coworkers and other roles like project management? Is it client team members where you're going to hand off documentation to them? And based on that audience, adjusting your approach accordingly, you really want to document where the right people are going to see it. So if you are giving information to a project manager, you wouldn't want that information to be in code comments where they're not likely to go look. But in the same and the same side there, your project manager probably doesn't need to see the really technical details of your code comments, and so those make sense to go into your code where they don't need to go in and see it. You don't need to put those into a project management or a task management solution. Um, that audience also includes yourself. Uh, in the future, um, you want to be able to document where you're going to be able to find it later. And so, for example, if I'm writing notes about how a task is going or what information I need to remember as I'm going through it, I'll put that in the task management system so that when I go back and look at that task later, that next information, that context is right there.

Remember too, that search is your friend. And I think a lot of apps we're seeing now are kind of adopting this kind of command k approach where you can easily get to search. And so I often when somebody will ask me a question or when I'm looking for information, search is always the first thing I do, as long as I know which app I've, uh, been doing that in, I can easily go in and find a link or an information that I can provide. One thing I think that's important to stress is that in in your documentation, avoid using words like just or simply that. Assume a level of understanding that may not be there. You know, that really increases cognitive load for your reader, who may be yourself. If you are looking at that document and you're dealing with an issue, say that's something that's come in, that's urgent and you're trying to follow instructions that say, just do this. And you have for whatever reason, you're unable to do that. That's really increasing your stress on what may already be an urgent issue that you're already stressed about, and you've just made that even harder.

And when it makes sense in your documents, and especially when thinking about knowing your audience, include visuals and external links. So things like screenshots of settings pages are always good, or links that provide more in-depth info on a certain topic, and that helps provide additional context and wayfinding for somebody who's trying to get into those instructions. Talking a little bit about documenting code and comments. There's an argument that your code should describe itself. It should be self descriptive in that comments and code are just noise because they get outdated. And I hear that argument. But I think what that doesn't necessarily account for are things like business logic from a client. So when that is in your code, make sure to include that information when needed. I also like just including comments in general, where it's helpful for a developer who is newer to something in that who might be looking at it later, they can become more familiar with parts that might otherwise be more complex.

Another thing I like to document are what are called magic numbers. So just specific numbers in your code that don't really have an obvious reason for being used when those come up. I think that's where a comment is helpful to say, this is why this specific number is actually here. One thing I do when writing out new code, especially if it's kind of something I need to take multiple steps to complete, is that I will write out the steps that I need to take as comments before I've even written any code, and I'll just write my comments first. And then as I write that code in, I will fill that in below each step. So, for example, let's say I'm pre-processing a node. I might write comments first indicating that I need to check the node content type. I need to check for a specific field and see if it's not empty, and then I might assign that value to a variable that I could then use in a twig template. I'll write all those comments first, and then I'll fill out that code. So for example, of one thing where I learned this lesson is that there was one time I was got a phone call from a client who was dealing with an urgent issue.

It was related to not code that I had written, but it was code from a back end developer. And I, as a front end developer, is less familiar with it. And that backend developer just recently left the company. But I was kind of the primary front end developer on the project, and I got into this code and found that it was about a 500 line function with no comments in it at all. And I'm on the phone trying to deal with an urgent issue from a client who's trying to deal with her own problems, and that's definitely something you want to avoid if you can. So another thing I'll do, too, is that if there are links that I'm going to to get information, if it's something like a drupal.org issue or a StackOverflow comment, I will include that link as a comment right above that code. And that really just gives me a breadcrumb that I can follow back to my earlier thinking. Interesting, interesting. Interestingly enough, I have found over the years that there are a few ways I approach documentation that actually have some parallels to development practices.

So this is just kind of interesting to think about that. First, you might write an early return in a function. If you get an irrelevant input, you really just kind of want to step out of that function and be done with it. And in the same way, in your writing, you can kind of write an escape hatch that really tells somebody to stop reading if that information is not relevant to them. So, for example, we have tasks in our kind of prelaunch tasks in a typical project where we'll have a process for taking a site live on pantheon and some steps that we have to take for that. But if the client is hosting this, the site themselves, that task is still in a template, but they don't need to do anything for that task. So in that description of that task, we'll just include some information that says if you are not hosting the site on pantheon, simply mark this task complete. And that just lets them move on without having to read a bunch of information that they realize at the end isn't relevant to them.

Another thing to ask and document templates I feel are very similar. Think like weekly meeting notes. Make it easier to repeat same processes just like you would in a function. And then as I kind of mentioned previously, when we get closer to documentation driven development, if you write those comments as you plan your code. So the example I was talking about with preprocessing a node, because as you finished your code, your documentation, your comments are all finished as well, there's no extra step you need to take to go back and document your code. You've done it already, so it just makes that process a little smoother and easier, and helps make sure the documentation becomes part. Of the process. So something we say a lot. Is that something I hear a lot is that naming things is hard. I've started to see some sentiment lately that maybe it doesn't have to be, and I'm starting to kind of get on board with that. I think really the key takeaway for that is, to be clear, not clever. So using action based variables, things like get roles, save token, prepare data starting with verbs on those makes that helpful for them to be nice and clear.

And you can do the same with functions that identify state things like is open instead of maybe check if open or something like has profile picture. Incidentally, I found two that that kind of helps you keep the mindset. Totally unrelated to documentation, but just a good developer. Best practice of having small functions that perform one action. Now your function is named after what that should actually be doing, and your function then kind of remains nice and small because you've defined what it is when you. So we'll talk a little bit about architecture decision records or ADLs. These can be decisions that you make on a project. And they also can document kind of invisible standards. So things that you do by default that maybe aren't written down. And in an ADR, you'll include some context in writing about why a decision might need to be made, what the decision actually is, and then any consequences of that decision. These are meant to be kind of longer term decisions, but they don't necessarily need to last forever.

I think we all know that technology evolves. Things change quickly in our industry. And so you might change the status of that ADR, which might start as approved to superseded and then create another ADR that kind of changes your your path on that. And if you're interested in more on this, Lullabot director of Technology Andrew Berry actually had a really good talk in depth last year that was just entirely about eight hours after Bocanegra. What was interesting to note there was that Lullabot approach is more organization wide, so they'll write ads that are for their entire front end practice at Gravity Works. We're looking at kind of taking that approach now to, but ours right now are more so project focused like this, this one example here on the screen. And that just allows us to kind of plan out our decisions for a particular project based on those business rules, based on kind of the CMS and the technology that we're using. So I think the other thing too, to note is that documentation really helps you defend the decisions that you're making throughout the process of a project, and it helps you remember why you did what you did in the future.

I've had instances where a project will go on for a few months and maybe switch developers and things, and if you have those decisions documented, it makes it easier for you to either remember or look back on why you did what you did. So what about taking notes and meetings? I really want to stress that documentation is everyone's responsibility. Yes, even developers during meetings. I think it's really important for us to understand what a client's goals are and what their needs are, and ensure that our work is is helping to meet those, meet those needs and solve those goals problems. So I think it's really important for developers to be doing that too. When you're making those notes, I recommend not transcribing the full conversation. Don't feel like you need to have the entire readout of everything that's being discussed, and we'll talk a little bit about how recent AI tools can help with that as well. But do note important information decisions made during the meeting and any next steps that come up that might need to be taken.

I had mentioned a little bit about document templates. I think it's good to take advantage of those. And in your template, leave a space for agenda items that you prep beforehand so that you come into the meeting with your agenda items already written out, ready to go. You don't have to be thinking about those as you get into the meeting. You can get it right into the client meeting and actually discuss those problems. One tip that I found that's helped me as well as you can see on the screen on the right here, is using emojis to highlight action items in the meeting. So I'll just leave an emoji at the front of a line when some next step came up. And that just makes it easier for me to find those next steps after the meeting, and make sure I've jotted those down and moved them into like asana or task management platform, for example. Lastly, I'd say to recommend definitely writing down your next steps when you hear those, or when you realize during a meeting that you have a next step you need to take.

Um found that if a conversation with a client wraps up and those next steps aren't clear, you say, okay, yep, we're moving on. But you haven't actually figured out what those next steps are. You aren't going to move forward successfully. So in order to do that, take a pause. Uh, get that next step and then write it down so that you can refer back to it later. Lastly, I found this process very useful. It's something I call checking out. So I mentioned I'm a team lead who splits my time between coding, attending meetings, and managing others on my team, and so I need to be able to when I'm doing my own development work, I need to be able to jump in and out without wasting a lot of time and energy figuring out where I last left off and what my next steps are. So what I'll do is when before I switch projects, or whether it's the end of the day, or especially if I'm going into a weekend or a vacation, I will just leave a comment in the task that I'm working on if I'm not done with it, that notes where I left off and what I think my next steps are.

And again, that just leaves kind of that breadcrumb back to my earlier thoughts, so that the next time I get into it, I can follow that path again and more quickly get back into my task. And you're with that. You're reducing friction. It's just like if you were kind of building a habit of wanting to go to the gym every morning and you leave your gym clothes out the night before so that they're ready to go, and you don't have to think about it. You just grab them and go. Um, it's just kind of the same, same concept there. And so this helps me more easily get back in, spin back up and be productive on a project. But I've also found that that same process helps other team members who might be checking in on my work, understand where I'm at and how things are progressing. Um, and then that prevents them from needing to check in with me. So from a managerial side, I always try to avoid micromanaging where I can. And so if I'm able to go in and see somebody's comments on the task where they've written out what they're doing and what's next for them, I can avoid interrupting them to just get that same status update, and then that allows them to stay focused on their work.

But it also still gives me, as a manager, the information I need to say, see how things are going, see if I need to step in to help things like that. So psychologist Mihai Mihai said in his well-known book flow, he said retrieving information from memory storage and bringing it into the focus of awareness, comparing information, evaluating, deciding all make demands on the mind's limited processing capacity. So all of these practices that we've talked about are really meant to encourage the idea of flow for a developer, that's the ability for them to sit down and really focus on the project and problem solving as focused as possible, without friction or without confusion. I think that's really important for productivity and effectiveness for a developer. So documentation remains a hugely important practice even after a project is finished and we kind of talk through the phases of the project. But even after a project ends, it's almost where the documentation is. Usefulness can even increase because you're then going back to reference it as you're maintaining the project or as you're moving on to new work, and you want to use that previous work as inspiration.

That's where that documentation can really come in handy and sometimes unexpected ways. So I'm sure AI is on everyone's mind. I'm sure we'll hear plenty more about it today. We had several conversations about it yesterday. Um, I'll say I've been proceeding with caution somewhat on I. I think it's been nice to use it to speed up some workflows. Um, while still keeping the human element in place to review the output and make sure that it's useful for what I need. What I have found too, though, is that documentation can power AI tools, but it's hard to do that if those kind of same information was not in written form, if you just had a conversation about it, or if it's just a thought that you have in your head, I can't really do much with that. Um, so just to mention a couple of tools here. Uh, tools like notebook LM, which is a recent offering from Google, but then also services from apps you may already be using, like notion, which is where we do a lot of our meeting notes and our planning AI services.

And that can help surface new insights or provide quick access to information. So, as you may see in these screenshots here on the left, I've used notebook LM to aggregate some ideas from, uh, articles and books that I had read actually about documentation. Uh, and then on the right side, I'm able to quickly sift through information. So I'm asking a question in that 12,000 word document I mentioned for a project to just get some information. And then the answer from AI just gives me a quick access to that information. I also mentioned earlier that you can avoid transcribing meetings because I can help with that and many AI services over the years. I think this is really becoming popular, especially with Covid and remote work. I think this is just becoming more and more of a feature that many services provide. So we use fireflies to record, transcribe and summarize many of our meetings. Some others on our team have tried tools like Otter and Rewind um, that do similar things. The icon on the bottom left here is for a tool called Super Whisper, which is one of the few different kind of text to speech tools.

And one thing I think that that we found that that's helped to is that somebody who is a verbal processor, who really wants to have a conversation with you to talk through their problem, they can turn on some super whisper or another kind of text to speech app and get a written record of that that they can then document and use for referencing, whether it's for reading it later or for having I use it to summarize it. Of course. Disclaimer here is to please ask for consent before recording others. So one major component of documenting and learning from documentation is the practice of sharing what you know. And truly, I would say documentation is a team sport. It should be everyone's responsibility and everyone can benefit from it. You learn when you write documentation because you have to understand and think through it from top to bottom in order to produce documentation that others can learn from. And then, of course, on the other side, others can grow from what you've shared, but they also can help you refine that.

And you're kind of building a nice feedback loop there. And together you are all building collective knowledge, and you don't have to know everything to help someone learn. I think that's something I try to stress with my team. You don't have to know every everything in order to document something. You just have to maybe know something that they don't or share an experience that you have and share it with them. And that helps you to kind of build that collective knowledge and grow from one another. So we hear about shifting left a lot in the industry when it comes to things like testing and security. You know, just making sure that those practices are acknowledged and understood and considered as early and as often in the process as we can. And we do this with accessibility as well. Just ensuring that we're early in the project and then often throughout talking about things like plain language and color contrast and other design considerations and that we're really hitting that early and often.

And I've been thinking to myself lately, why not also do that with documentation? Ensure that we bring it into our process as early as we can, and then revisiting it and letting it grow as often as we can. So one more book quote that I was actually kind of surprised to read. Recently, I've been reading Dan Mall's new Design That Scales book. And Dan is a design systems practitioner and really a designer at heart. Not not so much of a developer, but he actually pointed out somewhat in the defense of a frontend developer. He said, who on the team actually makes working software only the engineers. Every other role is largely one of documentation. That was an interesting take. But when you think about it, his kind of defense of that was that whether they're diagrams or product requirements, strategy, strategy briefs, task descriptions or design comps, we're really working as developers with a lot of different documentation that comes to us from the other areas of of the company that really help us to build software.

And so that's where it's good for developers to build documentation into our culture, understand that its importance, and then also spread that to the rest of the team, so that we're really visiting it from every different aspect of our company and building out all throughout the process. So back to collective knowledge, a few different strategies that we can think about to help build that within a team. First is to write as you learn. So get your decisions, your thoughts, and your discoveries on paper while they're still fresh in your head. And documenting in your own words helps with memory retention, but others may also help. Read those notes and help you refine them, or provide additional context that may be helpful to you as well. So you're all learning from one another. Second is rubber ducking. So this is a practice of articulating a problem and writing your speech. And I often recommend to my team that if you are working through a problem and you get stuck for more than 15 minutes, that's usually about the time when it's time to ask for help.

But often what they found, and I've experienced this myself as well, is that when you stop and you write out that problem, you have to start from the beginning in order to provide enough context. And by the time you've finished writing that, you've figured out the issue on your own before you even finished writing out the question. So that kind of helps build that, build that knowledge and make that easy for you to solve that problem. Next is working in public. I think we found over the years that we aren't fully reinventing the wheel with every Drupal site that we build or any other site. Um, and so things that one person might share one day are very likely to be useful to, something another person will use in another day as well. Um, we do a lot of different work in a lot of different industries that gravity works, but a lot of legal aid organizations and athletic associations for high schools, for states, and those might be on different developers over the years, and they can all learn from what everyone does.

And so when team members have questions, I try to encourage them to ask those in public channels as they can, rather than in private DMs, which also helps you be able to search that information later, even if you weren't in that conversation originally. The other thing, too, is that if somebody asks a question, but then they figure out the answer themselves before somebody else answers them. What I'll see happen a lot is that people will go into like a slack thread and answer the question in their own response to themselves. And really, what that does is it just shows the answer to their question. It provides that path to see that the question and the answer and the kind of the thought process there, if they revisit that later, or if somebody comes and searches and finds that in the future, which is definitely something I've done. Lastly, answer questions with a link. I really like this process, and it's a good way to build up a library or a repository of documents across your company.

So if somebody asks a question and you go to answer it, but you can't find a link that answers that question, consider instead of just answering the question in text to them, consider writing the document and then linking them to that document so that they have a link that they can refer back to. You can then share that link later, and it really just builds up this library of documents that now your whole team can benefit from. So with collective knowledge, you and your team are more easily able to collaborate and support one another. And that's really something that's important to me as a manager and a team lead as well. So, for example, I went on vacation for about a week and a half at the end of last year, it was six hours ahead of the eastern time zone where I usually am, and I had kind of anticipated that it might happen where a client would have a server issue, that normally I'm the one who would deal with it and just fix it. But before I left, I made sure I had documented that process and shared it with the rest of the team just to say, hey, if this comes up, here's what you need to do to fix it.

Sure enough, it came up while I was in an Uber on the way home one evening, and before I'd gotten back to my hotel room, another team member had pulled up my documentation and was able to fix it and handle it without me. And so that just helps make sure that we can maintain that work life balance and allow people to take vacations. But it also helps make sure things continue to run smoothly when life happens in other ways. So when people are sick, they need to take a mental health day. If they have an appointment they need to go to or need to pick up a kid from a school. That just makes sure that if something comes up while they're not available, we have the documentation and the resources we need to get in and fix it. And lastly, I think you build up resilience as a team against employee turnover, whether that's things due to just standard turnover or things like the great resignation or layoffs, because you have that record documented of their previous thoughts and decisions. So in closing, I want to talk just briefly about how many companies have recently pushed for efficiency, how effectiveness might be a better goal to aim for, and how documentation can play a role in that.

So much has been said about how companies like meta have referred to 2023, and now also somehow 2024, as well as the year of efficiency, especially with the rapid growth of AI. And I found that this is what the layoffs, degradation and removal of services and features and a general push to do more with less. And something I've been thinking a lot about lately, and recently read some advice that resonated with me about how effectiveness is maybe more brilliant than efficiency. So efficient. Teams are those that adopt the earlier mantra also popularized by Zuckerberg and Meta, which is to move fast and break things. They really value urgency over relevancy or importance, and that leads to instability and errors and mistakes. Compare that to effective teams who build with more purpose and intention, and avoiding work that isn't relevant or useful. They are still building quickly and carefully, but more carefully and intentionally than an efficient team. I really think they also understand the value and usefulness of things, practice processes and practices like documentation that establish stability for the team and its individuals.

So think about if you're driving a car. You can be efficient by driving quickly, but you can be effective by making sure you're driving in the right direction. Done right is better than done quickly. And so documentation is where it's useful there to take the time to document, when you know it's going to help you and your team actually become more effective. When thinking about effectiveness in the age of AI, I think a key takeaway I have is that being effective means getting good at the thinking and problem solving that I can't do for you. Documentation helps to speed up that process, so it's good to take advantage of AI and other efficiencies when you can. I know I certainly do many days, but it's no substitute for the practice of actually considering, thinking through and writing down your decisions and your solutions. I think really that's where you start to make yourself irreplaceable, is when you can use that documentation to plan and problem solve, just based on your past. Experience and your team's knowledge.

So you may be questioning, I know I did when I was getting started and trying to build out practices and things, maybe questioning whether you can make the time to make documentation happen. I know especially being a consultant, there's a lot of juggling of priorities and dealing with fires and addressing issues quickly. And I hope throughout the session I've kind of shown how taking time to build documentation into the team's culture helps that team thrive. You're able to remove silos and build that collective knowledge, but also do it little by little. Like I said before, don't feel like you have to write 12,000 words in order for it to feel like you're actually doing documentation. Um, planning documents, code comments, status updates, all of that information all counts as well. And you can see something that lacks documentation and just gradually build it up. So the example I had mentioned before, of the kind of 500 line file with no comments in it, as I was thinking through that and analyzing it and figuring out what it actually did, I wrote those comments as I went so that I wouldn't have to go do that again, and neither would anyone else.

Now that's in that code. I'm able to reference it in future. Make make documentation everyone's responsibility. So like I said, documentation is useful for everyone and it really does, I think, belong as part of an effective developer's role. It really helps yourself. It helps you solidify and understand that knowledge, but it also helps your team learn from it as well. Finally tend to your garden. By that I mean documentation will inevitably grow stale over time if we're not careful. And so continually sharing links, reviewing and revising it helps to extend that documentation's usefulness. With that too, I would also recommend allowing comments and edits on those documents so that others can help contribute to it, and it prevents you from becoming a roadblock to keeping that documentation updated. It doesn't have to just remain your responsibility. If others find that they can make, they can do so as well. Lastly, make documentation part of your definition of done. So build it into your processes.

Make it a habit on projects and tasks just like we would as front end developers, we might make sure that the work that we do is responsive, that it's accessible, that it's performant. Think about making it documented as well. And if you don't have the documentation that you need from somebody else when you're working on a project, encourage them to write it and even help them do so if needed. We're all knowledge workers. We're all in this together, and I think documentation is one way that we can just help each other share and build that knowledge together and then grow as a team. So that. Thank you for your time. Sorry. We've got a few minutes. If anyone has any questions. Yeah.

>>:
You were talking about rubber ducking and that. Could you give like, a an experience with that? Sure. Yeah. I think like usually that's where like when I am working through a problem and I've spent just a little bit too long figuring something out. And I realized, okay, I need to ask for help. And kind of the idea of rubber ducking is when you have you have the rubber duck in your hand, and that's kind of the person that you're bouncing your ideas off of. And so you can do that with a little rubber duck if you wanted to. But I think the nice thing with, with my team is that we're in slack all day long and we're all talking to one another. So usually I will jump into the channel like we have a Drupal channel, for example. So I'll just kind of describe my problem of, hey, I'm trying to build out this view and the contextual Filter isn't working quite right or something. Here's what I've tried. Here's what I've looked into. What am I missing here? Does anybody see what what else I need to be doing?

And so just getting an understanding because you have to kind of you have to talk through what the actual problem is you're trying to solve from the beginning, or somebody's not going to be able to help you because they don't have enough context. So just giving that information is really kind of that process of rubber ducking it out. And then if you end up answering it yourself, that's where you don't necessarily need somebody to answer it. But it is still kind of nice to hit enter on that comment anyway so that you share. Oh yeah, I had this question. Now I know the answer to I can go in and reply to myself and give that answer, because somebody else may benefit from that in the future as well.

>>:
I'm going to I'm going to get the literal rubber duck. Yes. Not a bad idea. Anyone else? Yeah.

>>:
One of one of my frustrations and concerns nowadays is our use of chat and how often people are solving problems in chat. And for me, that's not as helpful a documentation like a different form or an issue ticket that's more structured and I find that much easier to search. I heard you talking about like searching slack and finding answers to questions, and I'm wondering if that's just an adjustment I need to make so that I actually use like Slack or chat as a place to search. To me, that is never quite resonated. Like to do a search in slack to the salt because. Because slack feels too chaotic, right? I go to the form or I go to the issue and I do my search there, and if people haven't solved the problem there, then I don't find it. And so what I, you know, my own personal practice is I ask a question in the form or in the issue, and then I go to the chat and I say, I asked this question there, please go answer it there. What are your thoughts. Yeah. Yeah. Well, and I think it's almost a response to, to just the conversations that happen throughout the day.

I think I've really tried to make sure our team is collaborative and that we take ego out of the equation too, that they feel okay to ask questions. And so I think that's where it just kind of naturally happens throughout the day that those kind of questions and those even like code snippets and things might get thrown into into slack. And so it's almost a response to it, almost of, okay, I'm pretty sure this information is over here in slack. I can probably search for it here. I think really with I, what I would love to have one day is like a single slack tool that says, I'm going to go out and search slack, asana, notion, code base all at the same time and feed whatever I want back just to do that. That way that's what I want in the future. But with slack, I think it is mostly just where that's the conversation is usually happening most days throughout the day. And so I think that's really where a lot of times I'll say, like, if we get an error message, I'm like, I bet somebody has asked this before, let me go in and search it on slack and see that.

So yeah, maybe it's a little bit of a mindset shift, but I think it also just has to do with like your team's culture where they ask questions, where they share info.

>>:
Yeah. Kind of building on that. So what I personally do is I found that there's a difference between. Um, my work slack and my personal slack. Because within work you have access to all the work channels and stuff. So what I do personally is I have a note, just a Google doc, or I will actually take a I'll copy the link from the slack conversation, and I'll post it in my Google doc and be like, I have headings for like few few issues, and then I'll just dump the slack link in there with a quick summary. Um, so that's easy from the work aspect because you have the work slack channel. But on the personal one, I kind of default what you do because like. You have. You don't have like a collective work slack. You have your personal slack that. Yeah, you're in like the Drupal channel and stuff like that, but it's a lot harder to search. So I do the same thing you do. So like. Basically, I'm reinforcing kind of what you said. I have two different methods for the two different things, whether there's an orchestral solution, don't know.

But like that's kind of what I do for that. Yeah. And I think I have seen that too from other team members too, who especially ones who are just getting started. Um, we use notion a lot for like our meeting notes and project requirements and things, and a lot of times I will see that they will have these little notes to self essentially that do very much what you're describing. I think where they're saying here is this view, this view I ran into here are links to either a slack chat or a StackOverflow issue or things like that. And it's almost just like their own little personal repository of things. And then where I encourage them to kind of take that next step is that if they because like some people will write out processes that they do to kind of get a site spun up or some sort of issue that they're dealing with. And I try to say, you know, that document may also help everybody else too, if they come into that same thing. And so that's where we kind of talk about taking that document that's only visible to them and pulling it into a form of like a wiki that we have in our notion, where they create an article that is mostly that same information, but now it's just accessible to the whole team as well.

But yeah, I do see that happening a lot too, where they'll kind of build that personal file of things to go back to, almost like a set of bookmarks.

>>:
Adding to that, that's exactly what we do. But at the very top we use a term. Your mileage may vary. So I always say that is documentation. When I got stuck in this part of the project, this is what I did might not be the best thing for you. You know, deleting all of your node modules might not be the best thing for you, but it really helped me out. So yeah, and I think that's where comments are helpful too, where you're able to say, hey, it didn't quite work for me. Here's why. Or I didn't quite understand why not. And then we kind of work through that together. So yeah. Cool. I'm going to make one other note that sort of as somebody very active in the Drupal backdrop communities at the project level, that one of my frustrations is that I think we went from, uh, 8 or 10 years ago, a culture of lots of small practitioners who were sharing things in public to teams that are now working internally, and not as much information is getting shared, not because people are selfish, but just because they don't need to, and really encouraging people that if to to think about not just sharing with your teammates, but with the community by sometime, I really encourage my team members to not just ask me questions, but to ask in a public forum where the whole community can be involved.

And I think, again, because of my experience in the community, that's very natural to me. But it's not to my team members, right? They don't they don't feel as connected to the community. And I think sometimes almost embarrassed to ask them publicly. And so I try to model that by asking very basic questions in public. And then I sort of a very often times I will ask a question in public and then point my team to my public question and say, you know, go answer. If you have an answer to my question answered in this public forum, not just for us, so that everybody can get there. No, I think that's great. And it's something I'm sort of talking with our team about, too, is kind of going out where we we have an issue with the module. We need to resolve it. Okay. We figured it out for ourselves. We wrote a patch. Well, why not contribute that back and have a comment in an issue queue about that as well? Or like when we work with with pantheon is our usual hosting provider. There's good conversation even from non employees and the pantheon slack.

So bringing those over to there I think. Yeah helps with that. And I think you're totally right to about the kind of level of imposter syndrome or fear that people will have to kind of go outside of their bubble to talk with other people. But I think even events like this show that it's a really welcoming and open and inclusive community. And so I think we all can. Definitely benefit from that. So great point. Great. Well thank you everybody. Appreciate it.