[DOCS] Rewrite getting started

docs/source/guides/getting_started/first_sub.rst

@@ -1,7 +1,7 @@
 Initial Subscription
 ====================
 
-Your first subscription should look something like this:
+Your first subscription file should look something like this:
 
 .. code-block:: yaml
   :linenos:
@@ -45,6 +45,9 @@ Lets break this down:
 The first :ref:`__preset__ <config_reference/subscriptions_yaml:File Preset>` section is where we
 can set modifications that apply to every subscription in this file.
 
+This snippet specifically adds two :ref:`override <config_reference/plugins:Overrides>` variables,
+which are used by the presets below.
+
 -------------------------------------
 
 .. code-block:: yaml
@@ -73,6 +76,8 @@ subscriptions to look like TV shows in the Jellyfin media player (can be changed
 one of the presets outlined in the comment above). Setting it as a YAML key implies that all
 subscriptions underneath it will *inherit* this preset.
 
+This preset expects the variable ``tv_show_directory`` to be set, which we do above.
+
 -------------------------------------
 
 .. code-block:: yaml
@@ -82,17 +87,11 @@ subscriptions underneath it will *inherit* this preset.
     = Documentaries:
 
 Line 12 sets the key to ``= Documentaries``. When keys are prefixed with ``=``, it means we are
-setting the
+setting the genre. This value will get written to the respective metadata tags for both TV show
-:ref:`subscription indent variable <config_reference/subscriptions_yaml:Beautifying Subscriptions>`.
+and music presets.
-For TV Show presets, the first subscription indent variable maps to the TV show's genre.
-Setting subscription indent variables as a key implies all subscriptions underneath it will
-have this variable set.
 
-To better understand what variables are used in prebuilt presets, refer to the
+Behind the scenes, this sets the override variable ``subscription_indent_1``. Read more about
-:ref:`prebuilt preset reference <config_reference/prebuilt_presets/index:Prebuilt Preset Reference>`.
+subscription syntax :ref:`here <config_reference/subscriptions_yaml:Subscriptions File>`.
-Here you will see the underlying variables used in prebuilt presets that can be overwritten.
-We already overwrote a few of the variables in the ``__preset__`` section above to define our
-output directory.
 
 -------------------------------------
 
@@ -104,8 +103,10 @@ output directory.
       "NOVA PBS": "https://www.youtube.com/@novapbs"
 
 Line 13 is where we define our first subscription. We set the subscription name to ``NOVA PBS``,
-and the subscription value to ``https://www.youtube.com/@novapbs``. Referring to the
+and the subscription value to ``https://www.youtube.com/@novapbs``.
-:ref:`TV show preset reference <config_reference/prebuilt_presets/tv_show:TV Show>`,
+
+To see how presets ingest subscription definitions, refer to the
+:ref:`preset references <config_reference/prebuilt_presets/tv_show:TV Show>`,
 we can see that ``{subscription_name}`` is used to set the ``tv_show_name`` variable.
 
 -------------------------------------

docs/source/guides/getting_started/index.rst

@@ -3,23 +3,20 @@ Getting Started
 
 Now that you've completed your install of ``ytdl-sub``, it's time to get started. This is a 3-step process:
 
-- Create your configuration file (if the :doc:`/prebuilt_presets/index` don't fit your needs)
 - Create your subscription file
-- Automate starting YTDL-Sub
+- Automate starting ytdl-sub
+- (Optional) Create a custom configuration file if further customization is needed
+
 
 Prerequisite Knowledge
 ----------------------
 
-.. _navigate directories: https://en.wikipedia.org/wiki/Cd_(command)
-.. _YAML syntax: https://yaml.org/spec/1.2.2/#chapter-2-language-overview
-
-
 In order to use ``ytdl-sub`` in any of the forms listed in these docs, you will need some basic knowledge.
 
 Be sure that you:
-  ☑ Can `navigate directories`_ in a command line interface (or CLI)
+  ☑ Can navigate directories in a command line interface (or CLI)
 
-  ☑ Have a basic understanding of `YAML syntax`_
+  ☑ Have a basic understanding of YAML syntax
 
 If you plan on using the headless image of ``ytdl-sub``, you:
   ☑ Can use ``nano`` or ``vim`` to edit OR
@@ -31,48 +28,31 @@ Additional useful (but not required) knowledge:
 
 Overview
 --------
-``ytdl-sub`` uses two types of YAML files:
 
-subscriptions.yaml
+Terminology
-~~~~~~~~~~~~~~~~~~
-Defines ``subscriptions``, which specify the media we want to recurrently download, like YouTube
-channels and playlists, SoundCloud artists, or any
-:yt-dlp:`yt-dlp supported site <blob/master/supportedsites.md>`. ``subscriptions`` use ``presets``
-to define how ``ytdl-sub`` should handle downloading, processing, and saving them.
-
-``ytdl-sub`` comes packaged with many
-:ref:`prebuilt presets <prebuilt_presets/index:Prebuilt Presets>`
-that will play nicely with well-known media players.
-
-config.yaml
 ~~~~~~~~~~~
-To customize ``ytdl-sub`` to beyond the prebuilt presets, you will need a ``config.yaml`` file. This
-file is where custom ``presets`` can be defined to orchestrate ``ytdl-sub`` to your very specific needs.
 
-Running ytdl-sub
+Must-know terminology:
-~~~~~~~~~~~~~~~~
+- ``subscription``: URL(s) that you want to download with specific metadata requirements.
-To invoke ``ytdl-sub`` to download subscriptions, use the following command:
+- ``preset``: Reusable YAML configuration, that can specify anything from metadata layout, media quality, or any feature of ytdl-sub, to apply to subscriptions. A preset can inherit other presets.
+- ``prebuilt preset``: Presets that are included in ``ytdl-sub``. These do most of the work defining plugins, overrides, etc in order to make downloads ready for player consumption.
+- ``override``: Verb describing the act of overriding something in a parent preset. For example, the TV Show presets practically expect you to *override* the URL variable to tell ytdl-sub where to download from.
+- ``override variables``: User-defined variables that a preset will use in its definition.
+- ``subscription file``: The file to specify all of your subscriptions and some override variables.
 
-.. tab-set-code:: 
+Intermediate terminology:
+- ``plugin``: Modular logic to apply to a subscription. To use a plugin, it must be defined in a preset.
+- ``config file``: An optional file where you can define custom presets and other advanced configuration.
+- ``yt-dlp``: The underlying application that handles downloading for ytdl-sub.
 
-    .. code-block:: shell
+Advanced terminology:
-        
+- ``entry variables``: Variables that derive from a downloaded yt-dlp entry.
-        ytdl-sub sub subscriptions.yaml
+- ``static variables``: Variables that do not have a dependency to entry variables.
-
+- ``scripting``: Syntax that allows the use of entry variables, static variables, and functions in override variables.
-    .. code-block:: powershell
-
-        ytdl-sub.exe sub subscriptions.yaml
-
-``ytdl-sub`` initially downloads all files to a defined ``working_directory``. This is a temporary
-storage spot for metadata and media files so that errors during processing- if they occur- don't
-affect your existing media library. Once all file processing is complete, your media files are
-moved to the ``output_directory``.
 
 Ready to Start?
 ---------------
 
-Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit of background on how ``ytdl-sub`` functions, read through the articles below to get started:
-
 :doc:`Step 1: Initial Subscriptions <first_sub>`
 
 :doc:`Step 2: Your First Download <first_download>`