"Getting Started with the TOM Toolkit" - Literal instructions result in tom_setup failing.

[JohnAPaice]

Describe the bug "Getting Started with the TOM Toolkit" (https://tom-toolkit.readthedocs.io/en/stable/introduction/getting_started.html) has a section which, when followed literally, resulted in tom_setup failing.

Current Wording and Issue The current state of the Getting Started guide tells you:

"We need to add the tom_setup app to our project’s list of INSTALLED_APPS in the settings.py file. Edit the list of apps so that it looks like this:"

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'tom_setup',
]

However, upon setting up my TOM, the list initially looked like this:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',
    'django_extensions',
    'guardian',
    'tom_common',
    'django_comments',
    'bootstrap4',
    'crispy_bootstrap4',
    'crispy_forms',
    'rest_framework',
    'rest_framework.authtoken',
    'django_filters',
    'django_gravatar',
    'tom_targets',
    'tom_alerts',
    'tom_catalogs',
    'tom_observations',
    'tom_dataproducts'
]

Replacing this block with the previous block, as the text suggests, caused the tom_setup app to not work, as it didn't include many of the other apps.

Suggested Wording "We need to add the tom_setup app to our project’s list of INSTALLED_APPS in the settings.py file. Edit the list of apps _to add tom_setup to the end, like so:"_

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ... other apps ... #
    'tom_setup'
]

Desktop (please complete the following information):

• OS: macOS 14.4 (23E214)
• Python Version 3.11

Additional context Thank you for the lovely software! Apologies if this is specific to my experience, or my reading, or comes across as excessively pedantic - I'm very new to working with software like this, and following literal instructions is often how I get to grips with things. I can see how the original text may not be a problem for experienced coders, so I'm hoping this change would help others like me!

[jchate6]

Hi @JohnAPaice Thank you so much for the feedback!

We will take a closer look and clarify the documentation to make things more explicit.

If you notice anything else that doesn't make sense please don't hesitate to let us know.

[jchate6]

@JohnAPaice if you would like to contact us directly for help or comments (or would like an invite to the slack channel), please feel free to send us an email at tomtoolkit-maintainers@lco.global

[jchate6]

@JohnAPaice It looks like you changed the settings.py AFTER running tom_setup. None of those other apps should have been present before that. Did you use the Quickstart at the top of the page and run the make-tom.sh script first? If so, then you should have skipped the Installing the TOM Toolkit and Django section and jumped straight to the Running the dev server section.

If this is the source of the confusion perhaps we should move the manual installation to a different page of the documentation. Thoughts @phycodurus?