Skip to content
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

Update README.md #269

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Conversation

The-Unsticker
Copy link

Old text implies that running the installer is all you need to do. New text explains that your platform is supported and strongly encourages people to click through to the installation documentation.

As per:
https://forum.sailfishos.org/t/the-developer-documentation-doesnt-cater-for-new-developers/14687

Old text implies that running the installer is all you need to do.
New text explains that your platform is supported and strongly encourages people to click through to the installation documentation.

As per:
https://forum.sailfishos.org/t/the-developer-documentation-doesnt-cater-for-new-developers/14687
@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@@ -12,7 +12,7 @@ Getting started with the SDK is a fairly simple process:

## Install

[Download the latest SDK](/Tools/Sailfish_SDK) installers and install it. Read more about [SDK Installation](/Tools/Sailfish_SDK/Installation).
The SDK runs in its own virtual machine on Linux, Windows and OS X. Read our [installation guide](/Tools/Sailfish_SDK/Installation).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you and welcome! Unfortunately there is a little of misunderstanding.

The most important nonfunctional feature of the SDK is that it does not lock the user into a virtual machine in order to enable cross platform development. Just parts of the SDK run in a VM and those parts are not those parts a regular user usually interacts with. From SDK user's point of view Sailfish SDK is a fully native development environment.

The suggested formulation suggests the exact opposite: that the user would be using the SDK from within a VM.

Beside that, installing one of the supported virtualization platforms is just one of the prerequisites that need an attention from the user prior to installation, so the notice should be more generic.

Also, better place for the notice would be the home page of the SDK https://docs.sailfishos.org/Tools/Sailfish_SDK/ which actually already contains such a notice - it is the second sentence, so already now it is quite hard to miss. It could be shortened and highlighted a bit more though, like

- After downloading the SDK for your platform, please follow through with the [installation instructions](/Tools/Sailfish_SDK/Installation).
+ Please read the [installation instructions](/Tools/Sailfish_SDK/Installation) first.

The sentence would be also better moved above the links to installers, so that it is read first.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your reply and I accept your concern about implying eg the IDE runs in a VM.

The Tools page is fine at a glance. The Installation page likewise.

The problem as I see it is with the Apps page.

It says:
"Getting started with the SDK is a fairly simple process:

Install
Download the latest SDK installers and install it. Read more about [SDK Installation]


It implies that running the installer is all it takes.

Installing the SDK is not a simple process. It is the most complicated installation I've done in 30 years, including unlocking my phone and installing Sailfish.

This declared simplicity further inclines people to ignore the "Read more about" line.

So both the declared simplicity and the "Read more about" line ought to be changed.

Important high-level & introductory information for the top of this page would be:

  1. This is the official/best documentation ie you're in the right place.
  2. The SDK runs on your system: Win/Mac etc.
  3. We will guide you through the process.
  4. Help is available on the forums.

Only #4 is addressed and much lower in the page and implies it's for help with coding.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants