Making do with plain text files
After my recent decision to scale back on GitHub issues and pull requests, I’ve found some traction again with plain-text files.
In a couple of Rails applications, I have a docs folder where I store several Markdown documents that serve as guides for some of the code. To this, I have added three files, FEATURES.md, BUGS.md and PLANNING.md. The features and bug files are self-explanatory, but the planning file might need some explanation.
GitHub has a feature called milestones that lets you set an end date for a milestone. You can also add issues to a milestone. I always thought it was a nice feature that mimicked a sprint from agile methodologies like Scrum.
The planning file contains the sprints I have set out for the next six months, with each sprint listing the planned features and bugs I will work on. It gives a nice top-level view of what’s ahead and is easy to update.
I’m still in the early days of this plain-text switch from GitHub’s own features, but I’m already seeing benefits. The files live in the application’s codebase, so updating them is easy in a text editor. Having these files in the code base reduces the amount of context switching I need to do. Features and bugs can be planned in one pane, with any related code being open in a neighbouring pane, side by side.
Finally, the files are plain text, so they can be manipulated by any scripts. I am considering an auto-generated HTML file that provides an overview of the project’s status. It would include the number of open issues, a roadmap for the next few sprints, and any open bugs.
The planning tools that cloud-based products like GitHub and GitLab provide are fine, but are definitely overkill for what I need. Making do with plain text files isn’t a step down; it’s just an easier way for me to manage these projects with minimal overhead.