ramilefu

I've been toying with the design of something similar here and there over the past couple of months. It never made it past the pen-and-paper stage though. Pleasantly surprised to find this today and will have to try it out for a work project.

My original motivation was the lack of OpenAPI definitions across projects, despite everyone agreeing their existence is a "best practice". As you suggest, developers just truly hate writing them. Unfortunately, even the "generate it from code" approach tends to be complicated and often feels duct-taped together.

Make that six! I’m in!

Depends on where you live. An “experienced engineer” is going to make a lot less if they live in Mississippi than if they were in California. 250k for the former is likely “top dollar”.

Sounds like it wouldn’t save them a single #if, if they are already at 0…

There is a screenshot in the README…

Certainly. I’ve leaned into it, when given the chance.

As the author writes, it definitely makes you stand out, if you are willing.

The difficult bit here is the tendency for developers to detest these parts of the job. In my experience, most developers would prefer nothing more than to write code in a cave, never to share a word with anyone. Reviewing a PR, writing documentation, and sharing knowledge are all things taking time away from their passion.

I think this is the origin for much of the friction we experience in collaboration and documentation. It’s easy to build something, ship it, and move on. That’s the dream we are sold as well: changing the world, one line of code at a time, from our basements.

I would love to see more focus on writing in our industry. Unfortunately, I haven’t experienced much improvement here in the last decade of working in the industry, across several organizations.

The writers among us are quite the minority.