The Importance of Technical Writing
Making your Repo’s ReadMe better
No this blog is not going to go over how to fill your Github Repo pop with Markdown tips and tricks. I’m going to go over the essential element of these readme’s and that’s explaining how to use your code. To be fair, I’ve not written a lot of readme’s so I can’t tell you that what I’m about to tell you will work. What I can tell you is my experience using other people’s code and not really knowing what I’m supposed to do during certain moments.
In order for me to explain what I mean let me make recreate a situation I’ve recently run into. Let’s say you downloaded what seemed like a helpful NPM package that will reduce the amount of code you have to write to put in options into a drop down list for a user to select from. It works exactly like it’s supposed to, but then you realize that the CSS is just slightly off from the width of your selection container. You think, this must be easy to edit and you search through the documentation and they say to you can customize the CSS, but they don’t exactly tell you where to do this. Do I do it in the CSS for the App, the Component, do I put it inline when I create it? There was no clear answer.
Well that leaves you stuck, you can try and put it into Stack Overflow or Google but if no one has really tried to customize the CSS then you’re not going to find your answer. This is where I find the most difficulty in trying to use other people’s code, packages, gems, or other modules. At times the documentation leaves a wanting for more information or examples. It’s a fatal flaw that coders sometimes commit, you can write clever and helpful code but if you’re the only one who knows how to make changes then no one else is going to try and use it.
Well this is how you can approach making better ReadMe’s for your Github:
- Be Clear
Many times people are going to just try and install, jump head first, and not look at your documentation. Especially if it looks like a hot mess and that there may not be important information. You may not be creating the next Language or Framework Documentation, but take a page from what they’ve done. They have clear sections or table of contents in order for coders to quickly access information. They also make sure that important sets of information are easily legible. Just like code keep it clean and keep it clear.
2. Be Thorough
If you’re going to mention that certain things are customizable then you better include examples of how to do that. While experimentation can help coders figure out how to implement the customization, showing examples and placing some step-by-step situations into your ReadMe can help solidify how to do it. Don’t just tell people that they can customize, it can lead to hours of frustration and just make people uninstall what you’ve created.
3. Explain to Someone Who Doesn’t Code
I do this with my partner all the time. I let her read anything that explains what my code does to make sure it makes sense even to people who don’t know how to read or write code. This is important because if an up and coming coder comes and tries to use your work they are going to have questions if you just throw large concepts into something you want everyone to use. You don’t have to break down every concept, there can be an expectation of base knowledge. However, if they only questions an outsider has about your ReadMe are things like GET request, REStful, MVP, so on, then you did a great job explaining your code.
Overall, try to make details clear in your ReadMe so that you can spread your genius to other coders! Happy Coding Everyone!
