Raising more awareness of this great tool

[suzuki-shunsuke]

Discussed in https://github.com/orgs/aquaproj/discussions/1650

^{Originally posted by sheldonhull February 20, 2023}
Let's brainstorm.

This is one of the best tools for setting up my CI & local environment to be similar and far better than a bunch of custom bash scripts.

Because it offers version pinning it provides better control in CI than using brew and is far faster typically.

I want others to be aware of it.

A few ideas:

• Join the discord gophers group and get a channel for the project to raise visibility. Join the discord gophers group and get a channel for the project to raise visibility #1660
• Highlight it as an alternative to brew for cask like tools that offer better version control. Highlight the benefit of aqua aquaproj.github.io#268
• More quick start with devcontainers showing up as an available feature. Development Container Support #1659

[suzuki-shunsuke]

#1650 (comment)

Thank you for your proposal.
I'm really glad that you like aqua.

Join the discord gophers group and get a channel for the project to raise visibility.

This is a good idea to make aqua more popular, but I have a concern.

Ideally, I'd like to keep discussions in one place (GitHub) so that users and maintainers can find the information and track the topic easily.
If the information is dispersed, users can't find the information and track the topic.

When I checked an issue of a project, I was dissappointed because they talk about the issue in discord and I couldn't catch up the status of the issue from the issue. I saw discord, but in the channel various topics are discussed and I couldn't find the information about the issue.

I'd like to avoid the same situation.

And it isn't good to discuss the same topic in the multiple places.

Chat is a flow style communication, so it is difficult to stock the information.
And we have to answer the same question for many times.

Users can post comments roughly. This is good for users but isn't good for maintainers.
Chat has no template unlike GitHub Issue, so user's question would lack required information so we have to ask users question to get required information. It's very tough work.

I hope the community will grow and users support each other without me, but it would not so easy.

---

I described my concern, but I have no idea to make aqua more popular and introducing discord seems good to me.

Highlight it as an alternative to brew for cask like tools that offer better version control.

We have already described the attractive of aqua, but we could emphasize and clarify them more and more.

• https://aquaproj.github.io/docs/overview#why-aqua
• https://aquaproj.github.io/docs/comparison/common
• https://aquaproj.github.io/docs/comparison/homebrew

More quick start with devcontainers showing up as an available feature.

Related discussion: https://github.com/orgs/aquaproj/discussions/1273

Sorry but I'm not familiar with devcontainers.
I learnt devcontainers before, but I forgot. 😅

[gedw99]

Hey @suzuki-shunsuke

I am a bit of a newbie to aqua but i noticed the following things that make it hard to start:

1. Blog and docs and code dont matchup.

https://dev.to/suzukishunsuke/support-building-tools-written-in-go-2l10

when you do this, the cli commands do not do what the docs say. Its because of versioning perhaps.

2. The docs are messy.

It would be better if it showing you things in a progressive learning way.

3. It would be way easier to integrate aque into automation workflows if each aqua command has a flag to output the result as json

Then you can parse the json and then do the next command chain.

NATS cli does this and its a god send.

nats stream add --json

[gedw99]

I agree it is one of the best tools out there. Better than brew or hermit so far.

[gedw99]

The docs style here is less messy IMHO
https://suzuki-shunsuke.github.io/github-comment/getting-started

[suzuki-shunsuke]

Thank you for your feedback.
I'm really glad you like aqua.

Blog and docs and code dont matchup.

Blog and docs and code dont matchup.

We don't maintain Blog posts after publishing once, so they would be old when the time passes.
On the other hand, we maintain the document continuously, so please refer to the document.

Regarding https://dev.to/suzukishunsuke/support-building-tools-written-in-go-2l10 ,
the package type go was deprecated and go_install is recommended now.
But you can still install packages such as mitchellh/gox according to the blog post.
If you can't install them well, please create an issue.

The docs are messy.

The docs are messy.

Thank you for your feedback.
I thought the document is well maintained and extensive, so this feedback was unexpected.

---

In my expectation, users would be able to learn aqua gradually as the following.

1. Top page and Overview : Learn the overview of aqua
2. Tutorial - Basics: Learn Basic usage of aqua by hand

Many users can start using aqua by reading them.

3. Tutorial Extras : Advanced Tutorial : Learn aqua more deeply
4. Reference : Reference

Tutorial Extras and Reference aren't mandatory to start using aqua, but you can refer to them while using aqua.

We provide the search powered by Algolia, so you can find the information properly.

---

But maybe we can arrange the document. Especially, Tutorial Extras and Reference can be improved.
I'll review them again. Thank you for your feedback.

It would be way easier to integrate aque into automation workflows if each aqua command has a flag to output the result as json

It would be way easier to integrate aque into automation workflows if each aqua command has a flag to output the result as json

Please create an issue if you have any proposal.
I'm interested in what you want and how you would like to integrate aqua with automation workflow.

[suzuki-shunsuke]

The docs are messy.

I have arranged the document and added the guide.

• https://aquaproj.github.io/
• https://aquaproj.github.io/docs/#how-to-learn-aqua

We improve the document continuously.

[gedw99]

Here is an example golang cli that has Json output

https://github.com/nats-io/natscli

If you honk it’s a good idea .

I think the command option is like:

—output-json

it’s nice becauuse you can hook into the cli and do automation ! Allows to build higher level systems with coupling

[suzuki-shunsuke]

Thank you for your comment.
I didn't know that tool.
I'm taking a look nats, but I can't understand how nats integrates with other tools at a glance.
I'll take a look further when I have a time, but I'll really appreciate if you tell me an example.

[gedw99]

nats-io/nsc#559

Sort of shows the json thing

[suzuki-shunsuke]

I understood. Thanks.
aqua has several sub commands, and which sub commands you want the option to?

Regarding aqua which, I created an issue the other day.

• Support outputting the detail of a command #1697

I want to know

• command
• expected output
• example to integrate with other tools using the output

[gedw99]

It’s up to you

I think all commands in nats can output json . That’s the point if you know what I mean

[suzuki-shunsuke]

I see. Thank you.

[suzuki-shunsuke]

Created a related discussion.

• https://github.com/orgs/aquaproj/discussions/2312