 All right. So, hi everyone. You have heard my introduction already. My name is Isha. I work as a developer and senior consultant with Mavericks Consulting, where an agile consulting startup, a lot of us used to work for ThoughtWorks before. So, we've brought over a lot of our principles and opinions and a lot of other things from ThoughtWorks. I'm going to be talking about a fairly important but also overlooked and sort of understated aspect of development, which is writing your readme's. And this is going to be, or I'm hoping it will be more of an interactive session. It's for me to learn from you as much as hopefully for you to hear me out about how I feel about readme's. So, I really, really request you to please talk to me as I ask you stuff. Otherwise, it's going to be very awkward. All right. So, let's start with getting to know all of you a little bit. Quick show of hands. How many people here are developers? A lot of people. Okay. That's cool. So, it won't be a total waste. That is good information. How many people here have been coding for less than a year? They're coding professionally. Okay. Yeah. All right. Less than three years. Obviously, more than one less than three. Okay. And everybody else who's a developer has been coding for more than three years. All right. So, me, I've been coding for seven plus years now. And I've worked with multiple technologies, multiple domains. I'm not a computer science graduate, so I don't know what about the theory of computer science. But I can write code, so I guess that's why they pay me. All right. Cool. So, let's get to the next point, which is what really is a readme? Who can tell me what a readme is? I do have a definition there. I'm not just going in blind. But yeah, I'd just like to hear from you what you all understand when I say the word readme. Sorry. The thing that you ignore, that's a very good one. That's exactly why I'm talking about it. All right. Let's... How about someone who doesn't ignore it? It's the first thing you read. It's the first thing you read. We have two very conflicting opinions here. I'm glad. I am very glad. This is going to be a success. All right. So, that answers what you do with it. But what is it? What you're going through. And reduction of what you're going through. Anything else to add? A user manual? That's an interesting point. I will hopefully address it. Yeah? A pointer to where the user manual is? Yes, that too. All right. So, I'll tell you what my definition of a readme is. I like you. That's the first thing I look at. And to me, it's like the first impression of your code, right? Because I help out with recruiting, I also do a lot of code reviews, right? And the first thing I look for is a readme. And to me, how a readme looks actually gives me a sense of how this person approaches development in the first place. And that, especially when doing code reviews for recruitment is a very important thing. So, it's like the face of your project. It's when I go in, what kind of information do I want, right? I do also have a Wikipedia definition, which says that it's a form of documentation, usually a simple plain text file called by a whole bunch of different names, can use markdown, have or not have, and a file extension. So, that defines the readme for us, right? But my title says, exploring the subtle art of writing and effective readme. So, let's try and define what makes a readme effective. I have a few points there. I realize now that the contrast isn't great, but it doesn't matter. It's a good thing we get to talk more. It's OK. Don't have to read it. Sorry. I'll read it out for you. So, ignoring what's on this screen right now, what do you all think would make a readme effective? Don't read out my points to me. That's what I think makes it effective. I want to hear from you. Update it? You're keeping it updated? Yes, for sure. What else? Concise. Should be concise, OK? Who feels that having a concise readme is not effective? Yeah, OK? I think if you have a problem or a question, there should be something on the readme that will guide you. All right, sure, OK. What else? For a long one. You prefer a long readme? OK, sure. Break out the section saying just find everything one page. OK, cool. So a long one broken down by section, well formatted. Yeah? Sorry, what? I didn't quite catch that. Top 10 Sago flow questions. Top 10 Sago flow questions, OK. All right, OK. That's an interesting one. But I don't think that counts as a readme of your application, really. OK, what else? Tells you how to start the project, OK? Any other thoughts on it? The project does. Tells you what the project does, yes, for sure. OK, yeah. How to contribute. How to contribute, OK? Yeah, if it's an open source or when there are multiple people coming in and contributing, it should have details about that. Cool, OK. So let me then read out what I think makes a readme effective, and I'll go through each of those one by one. So one, keeping it brief. Now, brief is kind of subjective, right? What does brief mean? Does brief mean it should be a one-liner? Does brief mean it should be five pages long? Does brief mean that there's an optimum length? Actually, as in the consulting world, the real answer is it depends. I'm a consultant. That's my answer to everything. It depends. Now, question is, what does it depend on? It depends on what you're trying to achieve through your readme, right? A readme can serve as, as we said earlier, how to get started with your project. It can serve as your documentation, as the Wikipedia definition says. It can serve as a contribution guide. It actually does all of those things, but the intent is, or what you need to think about is what you're hoping to achieve out of it. A few things that it should cover for sure is that it should give you information that is necessary to compile, run, and test your application. Now, let's say I'm somebody who, because I'm a consultant, I go and often work on legacy applications, right? Stuff that's already there. And then I need to help build on top of it. And when I go in, I don't want to bumble around the code trying to figure out how things work. What kind of prerequisites does that code need? What kind of things do I need to run it? Some common problems that people run into, which is actually one of my points there, that it should include common troubleshooting scenarios, right? As you said, it should definitely be constantly updated. Imagine reading something in the readme and then realizing it doesn't exist in the code anymore. It's quite discouraging and frankly annoying when you're going through something like that. But at the same time, it's not a documentation of your APIs. You can't put everything in your readme. You can't say, oh, it supports 150 different APIs, which it shouldn't do because microservices and all of that. But let's say you had 150 APIs. That's not the kind of information you want in your readme. It's just too much information at that point. And that is information that can be gotten from other parts of your application. But it should have information on how do I run the application? Where do I get started? How is it structured? What do I need in order to contribute to the application? For other information, you can have multiple guides. You don't have to put everything in there. You don't have to write things like, oh, it uses object-oriented programming and solid and dry and microservices and whatever else is in there. I don't need that information from the readme. The other thing which is very important is that it should be a part of your application code. I'm assuming everybody here uses some form of version control. Gate, hopefully not subversion or mercurial. But I'm going to assume gate. If you're using gate, your readme's need to be checked in as part of your application code because the intent is to help your developers get on boarded with your application as smoothly and as easily as possible. If you have it somewhere in, I don't know, Confluence or Google Drive or whatever, there still needs to be that manual process of somebody coming and telling me, oh, actually, the readme's in that random location somewhere. Again, kind of frustrating to have to go through a whole bunch of loops to figure that information out. It should include common troubleshooting scenarios, problems that people run into. Or if you see this error, it probably means you're running a wrong version of Node.js, NPM, whatever. Or if you see this problem, maybe go back and check if you have these environment variables set. That sort of information. Again, useful first place I look when I run into trouble. And you should clearly define the commands to be run to do different things within your application. If you want to tell me, oh, you have to run a Gradle command to achieve x, which Gradle command, I don't know. I would prefer if that information was right there in front of me when I'm setting up the project instead of having to go look through the Gradle file, try a few things, go to the command line, type Gradle tasks, that sort of stuff. And it also, at the end of the day, like I said, providing a smooth onboarding experience. And for that, the simplest thing you can do is have all the information in one place, clear, concise, effective. How does everyone feel so far? Anyone who disagrees with me? I won't bite, I promise. I just want to hear it. OK, that joke didn't go well. It's supposed to be interactive. Please, talk to me. I agree with you. You agree. Thank you. Thank you. Wake tree. All right, any thoughts so far on the stuff I've said, or if I've missed stuff that you prefer to have in your read-me's? Somebody who doesn't really read read-me's? Have I convinced you to at least start looking at them, if not really writing them? Sorry. OK. OK. What else? Sorry. An FAQ? Sure, yeah. But then, again, that depends. You could include it in your read-me if there's maybe a few ones, but if you're realizing that it's just going on adding stuff to it, it might be more helpful to move that out. You could still give a link to it in your read-me saying, hey, you can go find this here, but it might not. Maybe your read-me may not be the best place for it. But yeah, I mean, again, depends on your use case. What else? Any other thoughts? Some people put their build status at the top of the read-me, which only works on GitHub. Yeah, exactly. Right. So if you're using GitHub, you can try and use plugins to integrate your build status. But normally, for example, when you're trying to write something, you don't necessarily go back to GitHub to look at a read-me. For that, you should probably use build monitors. Those are useful. I can give another talk on build monitors next time. Cool. What else? Anything, any other thoughts on read-me? I will take that as a no. So hopefully, we've now agreed that we need read-me's. We think that we should all be looking at read-me's and writing read-me's, most of us, at least. And we've sort of gone through what, in my opinion, makes for an effective read-me. So the last thing to do is actually show you what I think an effective read-me might look like. I found this interesting template on GitHub the other day if I can open it. I can't click that. Let's see. OK, no worries. I can just look for it. GitHub, read-me template. Is that the one? That is the one. So that's another aspect of it, right? That even though information on read-me's is quite readily available, if you just type in the words, good read-me, yet I see a surprisingly high number of people who have no idea how to read-me's. And it's very difficult when going into a project for the first time in realizing there is no information available as to what to do with it. All right, so this is something I found which I think sort of quite aligns with how I prefer to write and what I think makes for a good read-me. It just starts with your project title, just a very quick short description of what the project does. It can have or should have some getting started instructions. So how do you get the project up and running on a local development machine? What kind of testing do you do? How do you run your tests? Deployment information, if needed, all of that should live in that section. What kind of prerequisites do you need? What software do you need to have running, especially if you are hoping to have specific versions of specific software, Python 3, PIP, X, NPM, Y, all of that information is useful to have there so that people are not constantly, oh wait, I don't have this. I go look up how to install and you run that. Any step by step guides that you can provide about installing certain things that are very specific to your development environment. Define a step, give the example of the command to run as I was talking earlier. Define the specific commands that your developers would need to run. And just go on until you're done with all of the commands. You can end with an example by getting some data out of the system, using it for a little demo. Some people, if you look on GitHub, they would include screenshots. So again, that works if you're using a GUI. If you're using a development environment, a text editor screenshots probably wouldn't work that well. How to run the tests in your environment, how to run different types of tests, how you end to end tests run. You can explain what these tests do and why. But again, that depends on what your system is and if you're using some very obscure testing techniques. Otherwise, you don't really have to do any of that. Any specific stuff around coding styles that you can give there, like, linting tools, the kind of linting tools you use, why they're there, specific requirements around that. Deployment information. You can talk about specific technology use, how to contribute, how versioning works. You can list your authors. You can provide licensing information. And you can provide acknowledgments if you want. This is, of course, a very generic, very high-level template. You can choose to use it however you like. You can add information. You can remove information. All of it is optional. But in my years of experience, having a good read me, having a good starting point into your application drastically increases the experience of someone who's coming in and reading your code for the first time. And, of course, other things still apply. You still want to write clean code. You still want to have it well-tested. You want to still use whatever good practices are standard to your particular choice of technology. But this is something that, in my opinion, applies to irrespective of what technology you're using. Right. There's also a lot of other articles on medium, on multiple other gists that talk about what a good read me should look like. And you can form your own opinions about that. I found some I agreed with. Some I didn't quite. But hopefully, this will get you started on the path of at least exploring the practice of writing read me's and making your read me's more effective. That's all I had to say on the topic of read me's. I think I've exhausted pretty much everything I had to say. If you'd like to talk more about clean code, agile, stuff around CI CD, please come talk to me. I've been doing this for a while. I have opinions, of course. I'd love to hear yours. If you'd like to explore working in consulting and agile, Mavericks is hiring. We are a bunch of fairly smart people, I think. I'm sure there'll be something for you to learn. So yeah, check us out. Come talk to me if you'd like. I'll be around. And thank you for listening to me.