-
Notifications
You must be signed in to change notification settings - Fork 37
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
base: master
Are you sure you want to change the base?
Update README.md #269
Conversation
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
|
@@ -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). |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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:
- This is the official/best documentation ie you're in the right place.
- The SDK runs on your system: Win/Mac etc.
- We will guide you through the process.
- Help is available on the forums.
Only #4 is addressed and much lower in the page and implies it's for help with coding.
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