Add more examples and use-cases in the documentation

[ilovelinux]

Description

Note

This issue is based on my experience.

Context

I was looking for a tool for a personal use-case and I found Task. It looks maintained and well documented, however...

Issue

... I am having some hard time understanding:

• What does it do.
• Why has it been created.
• Which problems does it solve.
• Which are the perfect use-cases.
• Which are the limitations.

Main pages on docs doesn't answer to those questions, neither the FAQ does. There are a few examples on Getting Started but they are very simple.

In fact, the only explanation about "what is Task" is in the website's homepage:

A fast, cross-platform build tool inspired by Make, designed for modern workflows.

But I have no idea about the advantages using Task instead of Make for "modern workflows".

Consequence

As now:

• It's not clear to me whether Task fulfill my needs or not.
• I'm not willing to spend time trying it, understanding how it works and its limitations.

So I'm not going to use Task:
❌ Because it doesn't fulfill my needs
✔️ Because Task advantages, use-cases and limitations, aren't clear to me

[sspinn-netfeasa]

+1

Particularly, I'd love some CI examples.

[standardloop]

In general, there are few task runners.

The most famous being make (Makefile).

Make was originally a build tool, but with the use of .PHONY targets people just use it as a task runner.

There is also just which is more syntactially similar to makefile,

Then there is mise, which is more of a package manager, but has tasks as well.

And then go-task (Taskfile).

---

• Q What does it do.
  • task let's you define reusable tasks to run.
  • Need to compile your code? Write a task that runs all the compile steps (for example clang, or gcc)
  • Need to format code? Write a task that formats code using a formater tool like prettier
  • Want to run test cases? Write a task to run test commands.
  • task provides this grouping for reusable tasks you would want to run.

You may be wondering why not just create a shell script that does this?

You can totally do that, but then you have a lot more to think about for example:

• how do you define task dependencies?
• how do you include tasks from another file?
• how do you know when a build needs to be rebuilt?
• etc..

---

• Q Why has it been created.
  • As an alternative to make (Makefile).
  • Makefiles are still widely used, but the syntax can be a little weird at first glance, task offers a more familiar yaml syntax

---

• Q Which problems does it solve.
  • I think the What does it do answers this one mostly

---

• Q Which are the perfect use-cases.
  • In software, there aren't perfect use cases, that is why it is nice to have options.
  • Example, there are a lot of programming languages because some are better at other things than others and some people prefer one over another.

---

• Q Which are the limitations.
  • Still figuring that out, the biggest limitation I have seen is that it just feels like another project dependency.
    • You need to install it whereas make is usually preinstalled on systems
  • Also it being yaml is a blessing an a curse, advance things can look strange

---

The number 1 reason I started using task is because a Taskfile.yml looks very similiar to a .gitlab-ci.yml which I have used a lot at work. Also task uses can use go template syntax like a helm chart would.

So for someone like me, task felt more naturally to pick up.

---

task is cross platform because it uses https://github.com/mvdan/sh. So you can write shell commands for a system that doesn't have it (like windows).