One of my goals at work for the past month has teen driving efforts to improve our internal documentation for front-end developers. It would have been easier undoubtedly to just rant about it at meetings and talk about grandiose projects. I chose rather to do something about it in my own work.
- Pull requests. I used to just put a descriptive title and leave the description empty, sometimes linking to the original issue. A call-to-action came from my coworker, who asked me for a brief summary of changes so that it’s easier for him to understand what he was about to review. So, I put in some screen shots of any UI/UX changes, a few lines about background, something about the context for the pull request, and finally a short list of the main changes. In the last couple of weeks, I’ve started also adding links to any relevant documentation I wrote, such as backend API endpoints or anything in our product wiki.
- Internal documentation. We use a popular open-source system to house our internal front-end documentation. So, I’ve made it a part of my workflow to document any backend API endpoints in our system. That way, some developer won’t curse my name and the day I discovered programming when they have to maintain or debug my code.
- How-tos and repo documentation. Taking my coworker’s request further, I expanded any developer documentation that lives in the repository. This is usually either how to get started or how to implement a new feature. The effort spent on this (and
README.mdin tow) will hopefully mean that other developers will find it easier to get going with the codebase.
I actually like writing documentation!
