[skip changelog] Mention interfaces in documentation introduction #1545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Merged

per1234 merged 1 commit into arduino:master from per1234:expand-intro

Nov 11, 2021

Merged

[skip changelog] Mention interfaces in documentation introduction #1545

per1234 merged 1 commit into arduino:master from per1234:expand-intro

Nov 11, 2021

Conversation

per1234

Copy link

Contributor

@per1234 per1234 commented Nov 11, 2021 •

edited by 91volt

Loading

Please check if the PR fulfills these requirements

The PR has no duplicates (please search among the Pull Requests
before creating one)
The PR follows
our contributing guidelines
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)
UPGRADING.md has been updated with a migration guide (for breaking changes)

What kind of change does this PR introduce?

Documentation enhancement

What is the current behavior?

Unlike the IDE and Web Editor, Arduino CLI is intended to be used directly only by advanced users. However, all types of
users are likely to visit the repository and documentation website. Some of these readers will not be familiar with the
meaning of the acronym "CLI".

The previous documentation introduces Arduino CLI as:

an all-in-one solution that provides [wonderful things] to use any Arduino compatible board and platform

Which sounds like something every Arduino user would be interested in.

Those readers might therefore get the impression this is some sort of GUI application like the IDE and be frustrated and confused after spending time to install and run the program, only to find that it doesn't apparently do anything when they run the executable (because they did it from a file browser or shortcut).

What is the new behavior?

The introduction in the repository readme and documentation website home page mentions that Arduino CLI's capabilities are provided via command line and machine interfaces.

It is a bit difficult to describe Arduino CLI's interface in a short introduction because, despite the "CLI" in the name,
command line is only one of the interfaces provided by Arduino CLI (the others being the gRPC and Go API). I added the
term "machine" to cover the others.

Does this PR introduce a breaking change, and is
titled accordingly?

No breaking change.

@per1234


 [skip changelog] Mention interfaces in documentation introduction

2badd02

Unlike the IDE and Web Editor, Arduino CLI is intended to be used directly only by advanced users. However, all types of
users are likely to visit the repository and documentation website. Some of these readers will not be familiar with the
meaning of the acronym "CLI".
The previous documentation introduces Arduino CLI as:
> an all-in-one solution that provides [...] to use any Arduino compatible board and platform
Which sounds like something any Arduino user would be interested in.
Those readers might therefore get the impression this is some sort of GUI application like the IDE and be frustrated
after spending time to install and run the program, only to find that it doesn't apparently do anything when they run the
executable (because they did it from a file browser or shortcut).
It is a bit difficult to describe Arduino CLI's interface in a short introduction because, despite the "CLI" in the name,
command line is only one of the interfaces provided by Arduino CLI (the others being the gRPC and Go API). I added the
term "machine" to cover the others.