Documentation improvements and clarity enhancements

[amondnet]

Description

Several documentation sections could be enhanced for better clarity and user experience. These are optional improvements that would help users better understand the CLI.

Proposed Improvements

1. Add Prerequisites Section

Location: docs/content/en/1.guide/1.getting-started.md (before Installation section)

Issue: Documentation jumps straight to installation without mentioning requirements.

Proposed Addition:

## Prerequisites

Before installing Asana CLI, ensure you have:

- **For Homebrew users**: Homebrew installed ([brew.sh](https://brew.sh))
- **For Install Script users**: curl and bash
- **For Source installation**: [Bun](https://bun.sh) runtime (v1.0.0 or later)
- An Asana account with API access

2. Clarify Self-Update Command Scope

Location:

• README.md:90
• docs/content/en/1.guide/1.getting-started.md:178

Issue: The asana self-update command documentation doesn't clarify it only works for install script users.

Proposed Fix:

**Note**: The `self-update` command only works for installations done via the install script. 
Homebrew users should use `brew upgrade asana-cli` instead.

3. Add .env File Context Clarification

Location: docs/content/en/2.features/3.configuration.md:98-124

Issue: The ".env Files" section is confusing because it only applies to source installations, not Homebrew/script installs.

Proposed Addition:

::alert{type="info"}
**For Developers**: This section applies only to source installations. 
If you installed via Homebrew or install script, use environment variables 
or the config file at `~/.asana-cli/config.json` instead.
::

4. Add Release Notes Links

Location: All update sections (README.md, getting-started.md)

Issue: Users updating might want to see what's new.

Proposed Addition:

See [Release Notes](https://github.com/pleaseai/asana/releases) for what's new in each version.

5. Improve Command Consistency

Location: Throughout documentation

Issue: Mix of bun run dev and asana commands can be confusing.

Proposed Clarification:
Add a callout box in getting-started.md:

::alert{type="info"}
**Command Variations**:
- Use `asana` for installed versions (Homebrew or install script)
- Use `bun run dev` when running from source
- Use `./asana` for locally compiled binaries
::

6. Simplify Homebrew Installation

Location: docs/content/en/1.guide/1.getting-started.md:22-24

Issue: The "Or in two steps" example adds unnecessary complexity.

Proposed Action: Remove lines 22-24 or move to an "Advanced" note section.

Benefits

• ✅ Clearer onboarding for new users
• ✅ Reduced confusion about command variations
• ✅ Better context for different installation methods
• ✅ Easier troubleshooting

Tasks

• Add prerequisites section to getting-started.md
• Add self-update command scope clarification
• Add .env file context callout
• Add release notes links to update sections
• Add command variations callout box
• Simplify Homebrew installation section

Priority

Low - Nice to have improvements, not blocking user experience

References

• Related PR: docs: rewrite README in English with documentation links #5
• Documentation review findings

[pleaseai]

🚀 개발 시작하기

이 이슈로 개발을 시작하시려면 gh-please CLI를 사용하세요:

gh please issue develop 9 --repo pleaseai/asana

📦 설치

gh-please extension이 설치되지 않았다면:

gh extension install pleaseai/gh-please

자세한 내용: https://github.com/pleaseai/gh-please