marmelab

I’ve spent years reaching for Makefile by default, but I recently started using Taskfile for my projects instead. While it’s still the industry standard, it often feels like a mismatch for the specific needs of a modern web stack… Since moving a few of my workflows over, I’ve found it much better suited for the way I work today.

Here are three features that convinced me:

=> Self-documenting by design

With Makefile, just getting a readable help output requires a cryptic grep | awk one-liner that’s been copy-pasted between projects for 40 years. Taskfile simply has a built-in desc field for each task, and running task --list instantly shows everything available with a clean description. It’s a small thing, but it makes onboarding new developers (or just returning to a project after a few weeks :) ) so much smoother.

=> Truly cross-platform without hacks

Make was designed for Unix. The moment someone on your team opens a PR from Windows, you’re suddenly wrestling with OS detection conditionals, WSL edge cases, and PowerShell compatibility. Taskfile was built cross-platform from day one. It uses sh as a universal shell by default, and if you do need platform-specific commands, there’s a native platforms field that handles it cleanly at the command level. No more fragile branching logic.

=> Built-in validation and interactive prompts

Adding a confirmation prompt or a precondition check in Make means writing verbose, bash-specific shell code that breaks outside of bash. Taskfile has prompt and preconditions as first-class features: one line to ask for confirmation before a deploy, another to verify an env variable is set. It works on every platform, out of the box, no shell scripting required.

In my opinion, Taskfile feels like a much more predictable and modern successor!

What do you think about it?

I’ve spent years reaching for Makefile by default, but I recently started using Taskfile for my projects instead. While it’s still the industry standard, it often feels like a mismatch for the specific needs of a modern web stack… Since moving a few of my workflows over, I've found it much better suited for the way I work today.

Here are three features that convinced me:

=> Self-documenting by design 

With Makefile, just getting a readable help output requires a cryptic grep | awk one-liner that's been copy-pasted between projects for 40 years. Taskfile simply has a built-in desc field for each task, and running task --list instantly shows everything available with a clean description. It's a small thing, but it makes onboarding new developers (or just returning to a project after a few weeks :) ) so much smoother.

=> Truly cross-platform without hacks 

Make was designed for Unix. The moment someone on your team opens a PR from Windows, you're suddenly wrestling with OS detection conditionals, WSL edge cases, and PowerShell compatibility. Taskfile was built cross-platform from day one. It uses sh as a universal shell by default, and if you do need platform-specific commands, there's a native platforms field that handles it cleanly at the command level. No more fragile branching logic.

=> Built-in validation and interactive prompts 

Adding a confirmation prompt or a precondition check in Make means writing verbose, bash-specific shell code that breaks outside of bash. Taskfile has prompt and preconditions as first-class features: one line to ask for confirmation before a deploy, another to verify an env variable is set. It works on every platform, out of the box, no shell scripting required.

In my opinion, Taskfile feels like a much more predictable and modern successor!

I wrote a deeper dive with specific code examples on how these features work in practice ;)

Ever get the feeling that modern web dev has become… a bit too complex?

Sometimes I catch myself thinking about the “good old days”. When you could just write some code, compile it, and run it without worrying about all the dependencies, the build tools, the client-side rendering, the server-side rendering, the server components, and all the other buzzwords that are thrown around in the web dev world… just code doing its thing.

And honestly, I think that feeling isn’t totally wrong. Maybe we can make things simpler, faster, more straightforward again.

So naturally… I decided to embrace the future by going back to the past: COBOL.

Here’s my (100% serious, definitely not questionable) migration story.

When I first started working on OSS projects, I really struggled with documentation. But after a lot of trial and error, I learned a lot about writing clear and helpful docs. Working on several OSS projects has also taught me just how essential good documentation is to the success of a project. So, I'd like to share with you some of the tips that have helped me improve (in the hope that they will save you the same headaches I've experienced lol):

• Guide first : Start with simple guides that focus on common use cases to help users get started quickly.
• Show, don’t tell: Use screenshots & screencasts early & often to visually demonstrate features.
• More code than text: Prioritize clear, working code examples over lengthy text explanations.
• Use plausible data: Craft realistic data in examples to help users better relate & apply them to their projects. I use faker.js for this.
• Examples as stories: Write examples in Storybook to ensure accuracy & consistency between code & visuals.
• The reference follows the guide: If an advanced user is looking for all possible options of a component, they can find them in the same place as the guide.
• Pages can be scanned quickly: Break content into short, digestible sections for quick navigation and easy reading.

Here's a doc example where I've tried to implement these best practices.

How do you approach documentation in your projects?