And why it should be yours as well.
Confession and Resolution
My approach used to be total procrastination, and I would wait until the end of a project (if at all) to address documentation. By the end of any decent-sized project, I felt overwhelmed going back to the start of what I had built in order to document it well.
I even found that my mediocre documentation attempts were failing at times simply because I had lost touch with the evolutionary subject matter understanding I had developed over the course of the project. This evolutionary knowledge is really, really important to capture, because it represents the ingredients for accurate documentation.
In my ongoing effort to do hard things well, creating good documentation for my projects is something I’ve made a priority. While it may sound tedious or onerous, I have discovered that starting every new development effort with a simple README has completely changed my perspective on documentation.
I now consider this approach my own mini version of Readme Driven Development. In fact, it’s become my favorite part of development. Okay, maybe that’s a bit hyperbolic, but this step is certainly among my favorite parts of development. When I cross the finish line on a project and find that the documentation is there waiting on me, 100% complete, it’s a great feeling!
Why have I become such a fan of the README?
It encourages me to start any new project with documentation.
We all know that documentation is not considered the most glamorous part of a developer’s life, but we can probably all agree how thankful we are to find existing documentation when we peek into a new code base for the first time. What better way to encourage yourself to document the actual code than by making documentation the first commit to your repo?
Unlike some developers who are always working on the same type of codebase, I don’t always know what my project directory structure will look like, but I know for sure that documentation is always appropriate.
These days, the README is my first commit to any new project repository. By committing to put meaningful content in the README at the beginning of a project, I now have a place to capture everything I learn about the project as I learn it.
And, I’m not just talking about an empty README file so that
git add has something to work with. I mean a solid first stab at real, meaningful documentation. I capture everything I know about the project and list every task I can think of. It serves as an ongoing means of reinforcing my understanding of the project and deliverables.
As a general guideline, here are some easy things to consider including in your first README commit, in no particular order:
- Dates: Any important dates for this project, such as start date, delivery deadline, or other important milestone dates.
- Author: This is you! At a minimum, include your name, company (if applicable), and email address.
- Reference Info: Any relevant project links such as issue lists, background documentation, or reference materials for any newcomer to the project.
- Purpose/goals: Why is this thing a project? What is the objective and what are the goals by which success can be measured?
- FAQ: Often an afterthought, FAQs represent some of the most important things to document. List as many as come to mind and then grow this list as new ones arise.
- Conventions: Less common, but any unique conventions that others may need to understand before digging in.
- License information: This will likely accompany a real LICENSE file that contains the nitty gritty details, but it never hurts to reiterate the usage restrictions on the intellectual property contained in the repository.
- Todos: An ongoing list of things that need to be completed for this project to be a success.
Bonus: I get to use Markdown, and Markdown is awesome.
The general convention for README documentation is Markdown. If you’ve never used Markdown, I highly recommend learning it. Markdown is a very easy way to transform your plain text files into nicely formatted documentation. Armed with only your text editor and a handful of new syntax conventions you can create very impressive documents without ever opening MS Word or Google Docs. Exporting HTML or PDF is also very easy.
Markdown has some really cool features. All the essentials are there: Tables, bulleted lists, hyperlinks, inline images, anchors and bookmarks, text formatting, and even more complex things like flowcharts and diagrams. Remember that Todo list I mentioned earlier? You can present those as checkboxes and then check them off as you complete them.
I’ve just scratched the surface of the capabilities of Markdown. Here are several great references to check out that will give you a much better idea what you can accomplish:
- Markdown Tutorial: https://www.markdowntutorial.com
- GitHub Markdown Guide: https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf
- Mastering Markdown: https://guides.github.com/features/mastering-markdown/
- Markdown Guide: https://www.markdownguide.org
As of the time of this writing, it’s the most downloaded and is actively maintained. Among other features, it offers real-time preview and intuitive keyboard shortcuts. Other Visual Studio Code extensions offering similar functionality can be found here.
I’m sure you’ve been there before. Looking at code that you’re 99% sure you’ve never seen before, yet your name is on it as the author. Things always have a way of coming back around. Always. Long after the project is over, it’s very likely that the documentation you create will be as much a part of your legacy as the source code itself.
If you’re looking to up your documentation game, I highly recommend starting your next project with a README. This approach has really helped me to strengthen my deliverables and level up my own contributions to projects. Even if you try it and don’t like it, at least maybe you’ll end up with better Markdown skills. Even that makes it worth the effort.
Still not convinced? Leave me a comment below and let’s start a dialogue!