Note: Some links in this issue summary require user name / password of drupal/drupal to access the site
Task for this issue
As a result of user testing, we need to make some edits to three topics that are part of the Installation chapter of the Guide:
- install-requirements.txt (Concept: Server Requirements)
- Take out the first sentence in the "What are the requirements for running Drupal?" section. (It is redundant with the header.)
- install-prepare.txt (Preparing to Install)
- The topic was confusing to read, so the Steps section needs to be restructured, as follows.
-
- Take out the introductory paragraph in Steps.
- Start Steps with a numbered list, where item 1 is: "Choose a method for installing.". Follow that (in the same step item) with a definition list giving these options (giving a brief description of each -- there is some text in the topic currently that can be adapted):
- Try a free online demo [use something like the description that is already in the topic for this one]
- Use a one-click installer from your hosting provider [use existing description]
- Use Drush [in the description of this one, make sure they know they will need to have command-line access to the site and have Drush installed, and link them to the install-tools topic]
- Install using the web installer [in the description, say they will need space on a local or hosted web server]
- For the next step, we need to tell them that if they are using Drush or the web installer, they will need to set up some hosting (this step is not in the page right now). Something like this:
If you choose to use Drush or the web installer, you will need to set up a URL and hosting for your site, either at an external hosting provider or on your own computer. Verify that the hosting is working by putting a simple HTML file up in the web root directory of the hosting, and visiting the URL for your site.
- For the next step, we need to tell them to set up a database and database user account, if they are planning to install using Drush or using the web installer. This needs more detail -- it was confusing to our testers. Maybe something like: "Create a database, along with a database user account with full access".
- For the next step, we need to tell them that if they have chosen to use Drush, they can install using the following commands (and provide the commands that are currently in the topic). But I think it may need to be clarified -- especially the database stuff.
- For the next step, if they are using the web installer, they need to download, unpack, and upload the files to the web root. This needs a lot more explanation than is currently there, and probably a screen shot. There are topics in the Extending chapter about downloading and installing modules that can be used as models.
- Take out the steps about making files and making things writeable. These are not necessary.
- Take out the existing last step saying to run the installer. This topic is about preparing to install. Make it a follow-on task instead (but make it clear they only have to do it if that is how they chose to install).
- install-run.txt (Running the Installer)
-
- Make the install-prepare topic be a Site prerequisite instead of Prerequisite knowledge. Take out the bullets (*) characters in both Prerequisite sections, because each will now have only 1 topic in the list.
- This needs a new step 1 that says that to run the installer, you need to point your browser at the URL of your hosting, or that you might be running the installer as part of a 1-click install from a hosting provider or demo site.
- In existing step 4, take out the part that says to make a database, and instead say to put in the information for the database you created in the install-prepare topic.
- The tables of fields/values for the database and site configuration steps should have the following columns: Field name, Explanation, Example value. Right now they have no Explanation.
- Add a follow-on task to the topic, suggesting to check the Status Report to see if there are any problems with the installation. Link to the prevent-status topic for more information.
Instructions
See https://userguide_new-drupal.dev.devdrupal.org/guidelines/instructions.h... -- but skip the section on finding a task to do, since you have selected this one.
Checklist for this task
- Is a patch file provided? If only one or a few topics were edited, you can instead attach the updated source file(s).
- Is the edit complete and correct?
- Is the work free from additional edits outside the scope of the provided guidelines or task?
- Is attribution provided? See https://userguide_new-drupal.dev.devdrupal.org/guidelines/guidelines.htm...
Comment | File | Size | Author |
---|---|---|---|
#8 | user_guide-fix_installation_chapter-2709523-8.patch | 23.45 KB | jojyja |
#5 | install-prepare-3.jpg | 27.65 KB | jojyja |
#5 | install-prepare-2.jpg | 88.23 KB | jojyja |
#5 | install-prepare-1.jpg | 84.5 KB | jojyja |
#5 | user_guide-fix_installation_chapter-2709523-5.patch | 7.85 KB | jojyja |
Comments
Comment #2
jhodgdonAdded one item... and a bit of reformatting.
Comment #3
jhodgdonComment #4
jojyja CreditAttribution: jojyja at Red Crackle commentedI am going to work on this.
Comment #5
jojyja CreditAttribution: jojyja at Red Crackle commentedHere is the patch. I have attached some screenshots as well.
Comment #6
jhodgdonThis looks very good! I think it needs a bit of work before it is ready to go though...
Here are some suggestions about the install-prepare topic:
a) First step about choosing how to install:
- In the Drush list item, add:
See <<install-tools>>.
- List item "Install using the web installer" -- this heading has a different grammatical structure from the other list items. I think the first word should be "Use" like the other ones?
b) The next couple of steps after the new one you added about choosing how to install -- please change the wording so instead of "you will need" or "you need to" or "you have to", it just tells you what to do. For example:
"you will need to set up a URL and hosting for your site" => "set up a URL and hosting for your site"
etc.
c) In those same steps, I think the "if you choose" phrases should say "If you are installing" instead. I thought "If you choose" at this point was kind of confusing, because they already supposedly made the choice in step 1. And even the "if you have chosen" that was in one of the steps was less direct than saying "if you are installing".
d) The Drush commands...
- In the drush command line, it says "name=Example" but in the next line, it says "example" (lower-case). This is inconsistent.
- I think it would be helpful to say in the explanation line something like "... the Drupal version you wish to install, such as 8.1.3".
e) "If you have chosen to use web installer, then you have to install the core software manually." This is confusing, because it has two meanings for the word install. See also issue #2699015: Copy edit: Use install, upload, enable, add, place consistently. We want to use the term "upload files" or "copy files" for the process of transferring files from place to place, and "install" only for the processes of running the installer or turning on a module. So, this should say something like "If you are installing using the web installer, upload the core software files manually."
f) Also in that same section, the part about creating a database and database user is a repeat of a previous step, so you can take that part out.
g) Come to think of it, see item 4 in the issue summary for this topic -- the database stuff needs more detail.
h) It seems like there is still a missing step in the web installer section. After following those steps, you would end up with the files on your local machine. But they need to copy them up into their hosting account.
I'll put a few notes about install-prepare in a separate comment in a moment...
Comment #7
jhodgdonHere are some suggestions for the install-run topic:
a) "You might be running the installer as part of a 1-click install from a hosting provider or demo site. The installer needs to point the browser at the URL of your hosting."
This is a bit confusing.
If they're using a 1-click install, probably they will be already pointed to the correct URL. If they set up their own hosting, that is when they need to navigate to the right URL.
So... I think we could rewrite this something like:
If you are using a 1-click install from a hosting provider or demo site, you will most likely see some or all of the following screens as part of the installation process. If you uploaded the core files manually, to start the installer, open a browser and visit the URL that you set up for your hosting.
b) Actually, that's it -- the rest of this topic looks great. Thanks!
Comment #8
jojyja CreditAttribution: jojyja at Red Crackle commentedHi! Thanks for the feedback. I have created a patch.
Kindly note that item 4 about the database has already been updated in Step 3 of install-prepare.txt.
Comment #10
jhodgdonOops -- your patch has a lot of changes in it that don't belong... it seems to be reverting the formatting changes I made in the structure* files from your other issue (and the attribution for your contributions to them). So, I didn't apply those parts.
The changes to the install* files look good though! Committed to the guide, with some formatting updates.
I also realized that "example" in the Drush commands was actually the name of the directory you want to use for the site, so I fixed that in the text. And we use the word "directory", not "folder", so I fixed that too.
Oh, and the images should have been png not jpg, so I converted them. Anyway, looks good! Thanks for the work!
Comment #11
jojyja CreditAttribution: jojyja at Red Crackle commentedThanks.
Wow! I'm not sure how those unwanted updates crept in. Will make sure they don't appear again!