Refactor "Development Guide"

[fstasi]

Describe the request

Make the "Development Guide" more clear and complete.

🙂 Potential contributors will have access to all the information they need to get started working with the project's codebase.

Describe the current behavior

The primary documentation for project development work is the "Development Guide":

https://github.com/arduino/arduino-ide/blob/main/docs/development.md

The information in this file is confusing, partial, and somehow outdated.

🙁 It is difficult and unfriendly for potential contributors to get started working with the codebase.
🙁 Support staff/maintainers spend time provide 1:1 assistance to those hoping to work with the codebase but unable to do so autonomously due to the deficiencies in the documentation.

Additional context

To do

• Point the "Theia IDE prerequisites" link at the specific version of Theia in use.
  • Create a Theia update procedure document that includes updating the link.
• Add link to additional development-related documentation in https://github.com/arduino/arduino-ide/blob/main/arduino-ide-extension/README.md#readme
  • The arduino-ide-extension/README.md content is currently easy to overlook. It might make sense to separate the documentation in this way, but if so there must be links between the documents.
• Move documentation content out of arduino-ide-extension/README.md?
  • It seems like there is already a lot of content there, and likely even more is needed. So it might be better to have the readme provide the overview, then move the rest to individual documents under a docs subfolder, linking to there from the readme.
• Document the i18n sync procedure
  • This is a very frequent task for contributors, necessary to get a passing CI run (related).
  • It might also be worth providing an overview of the whole system (outline in PM here). This information is not needed by community contributors, but the maintainers do need to merge the Transifex pull PRs so it is relevant to the repository. There is currently a folder dedicated to internal documentation: https://github.com/arduino/arduino-ide/tree/main/docs/internal
• Document Arduino CLI build dependencies (Arduino CLI build tool dependencies are undocumented #1558)
  • These are only required when the Arduino CLI dependency is pinned to a non-release ref. In this case, the following tools are required:
    • Task
    • Go
    • Posix shell

References

• Info re: "start the app in debug mode via the App (Electron) launch entry": Serial Monitor periodically corrupts post-ASCII output #589 (comment)
• https://github.com/arduino/arduino-ide/blob/main/arduino-ide-extension/README.md

Related

• Update Theia to 1.22.1 #791 (comment)
• https://arduino.slack.com/archives/C01S67MJFGC/p1653401933054349
• arduino-ide-extension README.md being outdated #1293
• Document application debugging procedure for project developers #474
• Add a project contributor guide #1419, Add a dedicated translator guide document #1494
• Arduino CLI build tool dependencies are undocumented #1558
• Update BUILDING.md #1281
• There is no proper docs for who want to contribute first time? #172

Additional reports

• https://forum.arduino.cc/t/how-does-one-install-the-linux-ide2-1-0-zip-file/1118028/3
• Compiling Arduino IDE from source throws errors #2007

Issue checklist

• I searched for previous requests in the issue tracker
• I verified the feature was still missing when using the latest nightly build
• My request contains all necessary details