The INSTALL.txt file that is included in Drupal core is outdated, very long and contains many details that, in my opinion, are not very relevant to the installation process.

This information could better be stored on line on drupal.org than inside Drupal core:

  • docs on drupal.org are easier to maintain
  • more up-to-date and better written Installation instructions already exist on d.o. http://drupal.org/documentation/install
  • d.o. docs can easier link to information that is interesting but not immediatley relevant to the installation (currently INSTALL.txt includes such topics as cron configuration, multisite installation, "what is a module", building and customizing your site)
  • drupal core becomes, yet, a little bit, easier to maintain
  • on d.o. it is easier to keep a consistent style and make larger document changes

The INSTALL.txt file could include a short installation overview with one or several links to d.o

One could argue that you need off line installation instructions but is it still realistic in this day and age that one installs a web content management system without internet connection? Furthermore the INSTALL.txt is littered with links, so the current version is not as off line as it seems.

CommentFileSizeAuthor
#2 INSTALL.txt2.79 KBbatigolix
#1 drupal-put-install-txt-on-line-1942316-1.patch20.65 KBbatigolix

Comments

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
StatusFileSize
new drupal-put-install-txt-on-line-1942316-1.patch20.65 KB

First stab at replacing the existing content in INSTALL.txt by a compact installation instruction with plenty of links to d.o.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
StatusFileSize
new INSTALL.txt2.79 KB

Unfortunately the patch is not very readable, so find attached the actual INSTALL.txt

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Title: Put contents of the INSTALL.txt file on drupal.org » [proposal] Reduce INSTALL.txt (and update.txt etc.?) to abbreviated version with links to full docs on drupal.org
Issue tags: +Coding standards

Hm. The idea in the past has been that this type of important documentation (what is in the .txt files as well as the hook_help() docs, etc.) should be available to people who do not happen to be connected to the Internet when they are trying to use Drupal. So, we would need to consider this as a policy change before considering the patch itself.

Accordingly, adding a tag, and changing the title (when I first saw it I didn't understand what the suggestion was).

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Title: [proposal] Reduce INSTALL.txt (and update.txt etc.?) to abbreviated version with links to full docs on drupal.org » Rewrite INSTALL.txt with links to full docs on drupal.org

Shortening the title

kattekrab’s picture

kattekrab commented

I think there is still a use case for installing Drupal locally without connection to the internet. It's easy for us to assume that an internet connection is ubiquitous, but in some parts of the world that's not the case. People may have limited access and wish to work offline, using their internet access sparingly...

just my 2 cents.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Right. Or people could be on an airplane and not paying outrageous fees to be connected to the Internet at the time.

I think we should stick with the current philosophy. If we want to streamline INSTALL.txt, we could consider having a separate INSTALL-details.txt or something like that, but we shouldn't pull essential details out. Similarly, error messages in Drupal should not just say "Oops, look at this internet page for a solution".

Another reason not do refer to drupal.org pages: they are currently not translated. At least with a .txt file someone could supply a foreign-language version in a download.

serg2’s picture

serg2 commented
Issue summary: View changes

All necessary information for a standard installation should be contained within the core download. Looking at the INSTALL.txt of D7 it strikes the balance very well. (I always refer to it as can never remember tar -zxvf!)

Drupal 8.0.0-alpha14 does not seem to have one at all, which is how I found myself here, looking for issue which removed it, wondering if it was because of alpha status or a D8 change.

https://api.drupal.org/api/drupal/core!INSTALL.txt/8 has some addition information to https://api.drupal.org/api/drupal/INSTALL.txt/7 , mainly about re-installation which is handy and concise.

All over core docs and code there are explanations and comments of what everything is for, why it is there or what it could be replaced with. This is essential for anyone who is not an expert in exactly what they are are doing, which is most people. This should be encouraged.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Closed (won't fix)

I think this is a "won't fix". We do not really want to take information out of INSTALL.txt (which is now under the core directory).

Feel free to reopen and discuss, but as it stands,... for reasons stated in recent comments... no.