Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Critical Critical
    • Resolution: Fixed
    • Component/s: docs.moodle.org
    • Labels:
      None
    • Rank:
      25698

      Description

      The installation instructions are one of the most important parts of the documentation and it has become really hard to use with some information now (apparently) missing completely (e.g. minimum software versions).

      For example, a vital step is to ensure your database is set to UTF8. The path to find this is....

      http://docs.moodle.org/
      http://docs.moodle.org/en/Administrator_documentation
      http://docs.moodle.org/en/Administrator_documentation#Installation_.26_Upgrading
      http://docs.moodle.org/en/Installing_Moodle
      http://docs.moodle.org/en/Installing_Moodle#Create_empty_database
      http://docs.moodle.org/en/Create_Moodle_site_database
      http://docs.moodle.org/en/Create_Moodle_site_database#MySQL

      ....and finally you get the correct steps to create a database and set it up properly. That's 7 steps and only because I knew I was looking for it. There's no was a naive user will stumble across this unless they happen to be the type that reads documentation comprehensively. This isn't an obscure case either. It's setting up a MySQL database on a Unix type distribution which (even conservatively) must account for over 50% of installation scenarios.

      It used to be much easier before it was "improved" by splitting it all up.

        Issue Links

          Activity

          Hide
          Helen Foster added a comment -

          What we really need is a complete reorganisation and update of all pages in http://docs.moodle.org/20/en/Category:Installation so that newcomers to Moodle have easy to understand documentation on installing Moodle.

          Show
          Helen Foster added a comment - What we really need is a complete reorganisation and update of all pages in http://docs.moodle.org/20/en/Category:Installation so that newcomers to Moodle have easy to understand documentation on installing Moodle.
          Hide
          Helen Foster added a comment -

          I've done a first pass through http://docs.moodle.org/21/en/Category:Installation and deleted a bunch of pages which are not relevant to Moodle 2.x. Please find below my notes about the remaining pages after looking through them with Koen.

          Key pages

          i.e. pages which should be included in the TOC, though perhaps need the text rearranging over more or fewer pages

          Text from the original Installing Moodle page was rearranged over the following pages (some with rather weird page names). Perhaps it should be put back on one page?

          Perhaps the content of the following pages could be rearranged over 3 pages about installing Moodle on Windows, Linux and Mac:

          Text from the Cron page has recently been rearranged over the following pages as proposed in http://docs.moodle.org/21/en/Talk:Cron Is this a sensible way of organising things, or is it better to keep all the info on one page?

          Documentation about other software

          Should this info be included in Moodle Docs or should we just include links to other sites where the info can be found?

          Less significant pages

          i.e. pages with can be kept in the installation category but not included in the TOC or info moved to other pages and then deleted

          Please note that I'm certainly no expert in installing Moodle so some of the above notes may be totally wrong! Feedback and further comments would be much appreciated. Finally Howard, you should feel free to reorganise and improve the installation documentation as you see best!

          Show
          Helen Foster added a comment - I've done a first pass through http://docs.moodle.org/21/en/Category:Installation and deleted a bunch of pages which are not relevant to Moodle 2.x. Please find below my notes about the remaining pages after looking through them with Koen. Key pages i.e. pages which should be included in the TOC, though perhaps need the text rearranging over more or fewer pages http://docs.moodle.org/21/en/Installing_Moodle http://docs.moodle.org/21/en/Installation_FAQ http://docs.moodle.org/21/en/Installation_Quickstart Text from the original Installing Moodle page was rearranged over the following pages (some with rather weird page names). Perhaps it should be put back on one page? http://docs.moodle.org/21/en/User_site_capacities - out-of-date http://docs.moodle.org/21/en/PHP_settings_by_Moodle_version http://docs.moodle.org/21/en/Create_.htaccess_file http://docs.moodle.org/21/en/Create_Moodle_site_database http://docs.moodle.org/21/en/Creating_Moodle_site_data_directory http://docs.moodle.org/21/en/Moodle_site_moodle_directory http://docs.moodle.org/21/en/Install_Moodle_with_installer_script Perhaps the content of the following pages could be rearranged over 3 pages about installing Moodle on Windows, Linux and Mac: http://docs.moodle.org/21/en/Installation_for_Windows_2003_with_IIS http://docs.moodle.org/21/en/Installation_guide_for_Windows_using_EasyPHP http://docs.moodle.org/21/en/Installing_Moodle_on_Windows_Vista http://docs.moodle.org/21/en/Windows_installation_using_XAMPP - perhaps combining with http://docs.moodle.org/21/en/Complete_install_packages_for_Windows http://docs.moodle.org/21/en/Windows_installation - needs updating http://docs.moodle.org/21/en/RedHat_Linux_installation http://docs.moodle.org/21/en/Step_by_Step_Installation_on_a_Mac_OS_X_Server - perhaps combining with http://docs.moodle.org/21/en/Complete_Install_Packages_for_Mac_OS_X http://docs.moodle.org/21/en/Installing_plugins http://docs.moodle.org/21/en/Moodle_migration http://docs.moodle.org/21/en/Upgrading http://docs.moodle.org/21/en/Upgrading_FAQ http://docs.moodle.org/21/en/Upgrading_to_Moodle_2.1 http://docs.moodle.org/21/en/Verify_Database_Schema - useful info for when upgrading goes wrong, but the page needs to be more easily found http://docs.moodle.org/21/en/Cron Text from the Cron page has recently been rearranged over the following pages as proposed in http://docs.moodle.org/21/en/Talk:Cron Is this a sensible way of organising things, or is it better to keep all the info on one page? http://docs.moodle.org/21/en/Cron_with_MAC_OS_X http://docs.moodle.org/21/en/Cron_with_UNIX http://docs.moodle.org/21/en/Cron_with_Windows_OS http://docs.moodle.org/21/en/Cron_with_web_hosting_services Documentation about other software Should this info be included in Moodle Docs or should we just include links to other sites where the info can be found? http://docs.moodle.org/21/en/Installing_AMP http://docs.moodle.org/21/en/Using_the_Microsoft_SQL_Server_Driver_for_PHP http://docs.moodle.org/21/en/Installing_APC_in_Windows http://docs.moodle.org/21/en/Installing_Apache_on_Windows http://docs.moodle.org/21/en/Installing_MSSQL_for_PHP http://docs.moodle.org/21/en/Installing_MySQL_on_Windows http://docs.moodle.org/21/en/Installing_Oracle_for_PHP http://docs.moodle.org/21/en/Installing_PHP_on_Windows http://docs.moodle.org/21/en/Installing_eAccelerator_In_Ubuntu_Server http://docs.moodle.org/21/en/Upgrading_XAMPP Less significant pages i.e. pages with can be kept in the installation category but not included in the TOC or info moved to other pages and then deleted http://docs.moodle.org/21/en/1and1_MySQL_installation http://docs.moodle.org/21/en/Complete_install_packages - no point in general page, check info included in Mac and/or Windows pages then delete http://docs.moodle.org/21/en/Cron_reports http://docs.moodle.org/21/en/Cron_settings - content could be included in http://docs.moodle.org/21/en/Cron http://docs.moodle.org/21/en/Finding_and_Selecting_A_Web_Host http://docs.moodle.org/21/en/Installation_guide_-_Moodle_for_Windows_on_a_USB_Memory_Stick - seems very out-of-date http://docs.moodle.org/21/en/SUSE_Linux_Server_10 - seems very out-of-date http://docs.moodle.org/21/en/Step-by-step_Install_Guide_for_Solaris_10_with_Oracle_10 - seems very out-of-date http://docs.moodle.org/21/en/Step-by-step_Install_Guide_for_Zenwalk-5.0 - seems very out-of-date http://docs.moodle.org/21/en/Manual_installation_on_Ubuntu - seems very out-of-date http://docs.moodle.org/21/en/Step-by-step_Guide_for_Installing_Moodle_on_Mac_OS_X_10.4_Client - check info included in http://docs.moodle.org/21/en/Step_by_Step_Installation_on_a_Mac_OS_X_Server then delete (if mac is so easy, why the need for so many docs?) http://docs.moodle.org/21/en/Manual_installation_of_Moodle_2.0_on_Mythbuntu_using_Git - Mythbuntu is irrelevant, but the page could be a good base for 'Manual installation on Ubuntu using Git' http://docs.moodle.org/21/en/Unexpected_installation_halts - perhaps these be reviewed and then added to Installation FAQ to make them more easy to find http://docs.moodle.org/21/en/FreeTDS http://docs.moodle.org/21/en/Masquerading Please note that I'm certainly no expert in installing Moodle so some of the above notes may be totally wrong! Feedback and further comments would be much appreciated. Finally Howard, you should feel free to reorganise and improve the installation documentation as you see best!
          Hide
          Howard Miller added a comment -

          Having been working on this for a few days now my driving policy is to make the information more succinct. I think the documentation has become spread over too many pages and some of it has become incredibly verbose (not in a good way).

          I'm happy to be overruled but I believe that we can/should expect users to have at least a superficial understanding of the platform that they are attempting to install Moodle on. It just becomes an unwieldy nightmare otherwise!

          Show
          Howard Miller added a comment - Having been working on this for a few days now my driving policy is to make the information more succinct. I think the documentation has become spread over too many pages and some of it has become incredibly verbose (not in a good way). I'm happy to be overruled but I believe that we can/should expect users to have at least a superficial understanding of the platform that they are attempting to install Moodle on. It just becomes an unwieldy nightmare otherwise!
          Hide
          Helen Foster added a comment -

          +1 for making the information more succinct and expecting a basic understanding. Thanks Howard

          Show
          Helen Foster added a comment - +1 for making the information more succinct and expecting a basic understanding. Thanks Howard
          Hide
          Martin Dougiamas added a comment -

          Good luck! Looking forward to seeing what you come up with!

          Show
          Martin Dougiamas added a comment - Good luck! Looking forward to seeing what you come up with!
          Hide
          Helen Foster added a comment -

          Just came across a couple more key pages which I think should be included in the installation category:

          http://docs.moodle.org/21/en/Git_for_Administrators
          http://docs.moodle.org/21/en/CVS_for_Administrators

          Show
          Helen Foster added a comment - Just came across a couple more key pages which I think should be included in the installation category: http://docs.moodle.org/21/en/Git_for_Administrators http://docs.moodle.org/21/en/CVS_for_Administrators
          Hide
          Howard Miller added a comment -

          Yep - already attacked the Git one. The main install pages and those that link directly from them should be more or less done. I keep revisiting pages as I find other information I didn't know existed but you should get the spirit of it if you want to have a look.

          Comments appreciated.

          I'll try to keep a list of pages I have updated to make it easier to copy them to 2.2.

          Show
          Howard Miller added a comment - Yep - already attacked the Git one. The main install pages and those that link directly from them should be more or less done. I keep revisiting pages as I find other information I didn't know existed but you should get the spirit of it if you want to have a look. Comments appreciated. I'll try to keep a list of pages I have updated to make it easier to copy them to 2.2.
          Hide
          Helen Foster added a comment -

          Many thanks for your docs work, Howard. Whilst the wikis will always be work-in-progress, I think it's time to mark this issue as resolved.

          Show
          Helen Foster added a comment - Many thanks for your docs work, Howard. Whilst the wikis will always be work-in-progress, I think it's time to mark this issue as resolved.
          Hide
          Martin Dougiamas added a comment -

          Thanks very much for your help Howard.

          Show
          Martin Dougiamas added a comment - Thanks very much for your help Howard.

            People

            • Votes:
              1 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development