Skip to content

dev-tools

Introducing mkdocs-editor-notes: Keep Your Documentation Clean While Tracking TODOs

TLDR

Track TODOs right in your docs without cluttering them. Use footnote syntax, get an auto-generated tracker page.

Writing documentation is hard. Keeping it up-to-date is even harder. When I'm writing, I inevitably encounter sections that need more work:

  • I should add an example here
  • Need to verify this with the team
  • TODO: Update this after the API changes
  • Does this make sense to beginners?

These thoughts are valuable—they represent improvements, questions, and reminders that will make documentation better. But where do you put them?

Makefile magic

TLDR

I have a cool structure, nice convenience functions, and flashy magic that "makes" my projects pretty awesome!

For a fairly long time, now, I've been including a Makefile in all of my projects. It's a nice way to provide access to actions that need to be done over-and-over in a software project. It's familiar (to most folks), works on almost any reasonable dev environment out-of-the box, and makes getting started on the project really straightforward.

Over the years, I've developed a lot of cool stuff that I like to include in my Makefiles. This ranges from some basic patterns and structures that I've found helpful to some fancy "magic" that makes it nice to work with.

make help example

Example of make help with my custom Makefile

Today, I decided to create a GitHub repo to showcase these patterns in a few example Makefile entries. I thought it might be nice to talk through what's offered there and explain some of the deeper magic.