Cleanup documentation and make it more readable

README.md

@@ -27,8 +27,7 @@ problem, but not in a VCS-agnostic way or completely user-friendly way.
 We want self-contained code repositories without any hassle for end-users.
 Dfetch must promote upstreaming changes, but allow for local customizations.
 The problem is described thoroughly in [managing external dependencies](https://embeddedartistry.com/blog/2020/06/22/qa-on-managing-external-dependencies/) and sometimes
-is also known as [*vendoring*](https://stackoverflow.com/questions/26217488/what-is-vendoring).
-See [vendoring](https://dfetch.readthedocs.io/en/latest/vendoring.html) for more information about vendoring.
+is also known as [*vendoring*](https://dfetch.readthedocs.io/en/latest/vendoring.html).
 
 Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools.
 See [alternatives](https://dfetch.readthedocs.io/en/latest/alternatives.html) for a complete list.

doc/index.rst

@@ -28,14 +28,14 @@
 .. toctree::
    :maxdepth: 2
 
+   installation
    getting_started
    manifest
    manual
    troubleshooting
    contributing
    changelog
    alternatives
-   examples
    vendoring
    legal
    internal
@@ -46,37 +46,19 @@ Dfetch - *a source-only no-hassle project-dependency aggregator*
 What is Dfetch?
 ---------------
 
-We needed a dependency manager that was flexible enough to retrieve dependencies as plain text
+We make products that can last 15+ years; because of this we want to be able to have all sources available
+to build the entire project from source without depending on external resources.
+For this, we needed a dependency manager that was flexible enough to retrieve dependencies as plain text
 from various sources. `svn externals`, `git submodules` and `git subtrees` solve a similar
-problem, but not in a vcs agnostic way or completely user friendly way.
+problem, but not in a VCS-agnostic way or completely user-friendly way.
 We want self-contained code repositories without any hassle for end-users.
 Dfetch must promote upstreaming changes, but allow for local customizations.
+The problem is described thoroughly in `managing external dependencies <https://embeddedartistry.com/blog/2020/06/22/qa-on-managing-external-dependencies/>`_ and sometimes
+is also known as :ref:`vendoring`.
 
-Other tools that do similar things are `Zephyr's West`, `CMake ExternalProject` and other meta tools.
+Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools.
 See :ref:`alternatives` for a complete list.
 
-Installation
-------------
-`Dfetch` is a python based cross-platform cli tool.
-
-Install the latest release with:
-
-.. code-block::
-
-   pip install dfetch
-
-Or install the latest version from the main branch:
-
-.. code-block::
-
-   pip install https://github.com/dfetch-org/dfetch/archive/main.zip
-
-Once installed dfetch output can be seen.
-
-.. code-block::
-
-   dfetch --version
-
 Basic usage
 -----------
 

doc/installation.rst

@@ -0,0 +1,86 @@
+
+.. Dfetch documentation master file
+
+Installation
+============
+
+From pip
+--------
+
+If you are using python you can install the latest release with:
+
+.. code-block:: bash
+
+   pip install dfetch
+
+Or install the latest version from the main branch:
+
+.. code-block:: bash
+
+   pip install git+https://github.com/dfetch-org/dfetch.git#egg=dfetch
+
+Binary distributions
+--------------------
+
+Each release on the `releases page <https://github.com/dfetch-org/dfetch/releases>`_
+provides pre-built installers for all major platforms, so no compilation is required.
+
+Each installer package has a name in the format ``<version>-<platform>``.
+
+- ``<version>`` shows the software version:
+
+    - If it includes ``dev``, it is a development release (for testing).
+    - If it is only numbers (e.g. ``0.11.0``), it is an official release.
+
+- ``<platform>`` indicates the system the installer is for: ``nix`` (Linux), ``osx`` (Mac), or ``win`` (Windows).
+
+The version is automatically determined from the project and used to name the installer files.
+
+.. tabs::
+
+    .. tab:: Linux
+
+        Download the  ``.deb`` or ``.rpm`` package from the releases page and install it.
+
+        Debian / Ubuntu (``.deb``):
+
+        .. code-block:: bash
+
+            sudo dpkg -i dfetch-<version>-nix.deb
+
+        RPM-based distributions (``.rpm``):
+
+        .. code-block:: bash
+
+            sudo dnf install dfetch-<version>-nix.rpm
+            # or
+            sudo rpm -i dfetch-<version>-nix.rpm
+
+    .. tab:: macOS
+
+        Download the ``.pkg`` package from the releases page and install it.
+
+        .. code-block:: bash
+
+            sudo installer -pkg dfetch-<version>-osx.pkg -target /
+
+    .. tab:: Windows
+
+        Download the ``.msi`` installer and install by double-clicking or use:
+
+        .. code-block:: powershell
+
+            msiexec /i dfetch-<version>-win.msi
+
+        Uninstalling can be done through the regular Add/Remove programs section.
+
+Validating Installation
+-----------------------
+
+Run the following command to verify the installation
+
+.. code-block:: bash
+
+    dfetch environment
+
+.. asciinema:: asciicasts/environment.cast

doc/troubleshooting.rst

@@ -3,23 +3,58 @@
 Troubleshooting
 ===============
 
-Although we do our best, *Dfetch* can always do something unexpected.
-A great deal of *Dfetch* functionality is dependent on plain-old command line commands.
+Sometimes *Dfetch* may not behave as expected. This is could be because it relies on
+standard command-line tools such as ``git`` to be available on your system. This section will help you
+diagnose problems and understand what is happening behind the scenes.
 
-First of all, it is important to see what tools the system has.
-This can be seen with :ref:`dfetch environment<environment>`.
+Step 1: Check your environment
+------------------------------
 
-Each command *Dfetch* performs and its result can be shown with increasing the verbosity
-with the `-v` flag. For example, if an :ref:`dfetch import<import>` is giving strange results, re-run it with::
+Before anything else, it's helpful to see which tools *Dfetch* can detect on your system.
+This shows missing or incompatible dependencies. Run:
+
+.. code-block:: bash
+
+    dfetch environment
+
+Compare the output to the expected tools your commands require.
+
+.. asciinema:: asciicasts/environment.cast
+
+Step 2: Use verbose mode
+------------------------
+
+If a specific *Dfetch* command gives unexpected results, run it with the ``-v`` flag
+to see exactly what *Dfetch* is doing:
+
+.. code-block:: bash
 
     dfetch -v import
 
-Reporting issues
-----------------
-We are glad to help, if you you are stuck, either create an issue_ on github or contact us through gitter_!
+Verbose output shows each command *Dfetch* executes and its result, making it easier
+to spot errors, missing tools, or other issues.
+There can be various issues with for instance contacting or authenticating with the remote
+repository or with local settings. By running the ``git`` or ``svn`` command in isolation
+the issue can be shown more clearly.
+
+Step 3: Reporting issues
+------------------------
+
+If you cannot resolve a problem, we're happy to help! Check for any existing `GitHub Issues`_.
+When reporting an issue, please include:
+
+1. The output of ``dfetch environment``
+2. The verbose output of the failing command (``dfetch -v <command>``)
+3. Your operating system and shell information
+
+You can report issues via:
+
+- `GitHub Issues`_
+- `Gitter`_ community chat
+
+.. _`GitHub Issues`: https://github.com/dfetch-org/dfetch/issues
+.. _`Gitter`: https://gitter.im/dfetch-org/community
 
-.. _issue: https://github.com/dfetch-org/dfetch/issues
-.. _gitter: https://gitter.im/dfetch-org/community
 
 Security issues
 ----------------
@@ -29,5 +64,5 @@ You can report issues by opening a confidential issue via `GitHub Security Advis
 `GitHub's private vulnerability reporting`_ for more info. If you have no contact please contact us through
 the mail listed in the pyproject.toml.
 
-.. _`GitHub Security Advisories`: https://github.com/dfetch/dfetch/security/advisories
+.. _`GitHub Security Advisories`: https://github.com/dfetch-org/dfetch/security/advisories
 .. _`GitHub's private vulnerability reporting`: https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)

doc/vendoring.rst

@@ -1,7 +1,7 @@
 .. Dfetch documentation master file
 
-Vendoring Dependencies
-======================
+Vendoring
+=========
 
 Vendoring is the practice of copying the source code of another project directly
 into your own project's repository. Instead of relying on a package manager to
@@ -322,6 +322,16 @@ Real-world projects using vendoring
 - `Kubernetes - (Go) <https://github.com/kubernetes/kubernetes/tree/master/vendor>`_
 - `Cargo - (Rust) <https://doc.rust-lang.org/cargo/commands/cargo-vendor.html>`_
 
+Real world projects using Dfetch
+--------------------------------
+
+Here are some links to example projects using *Dfetch*.
+
+- `Dfetch`: https://github.com/dfetch-org/dfetch
+- `ModbusScope`: https://github.com/ModbusScope/ModbusScope
+
+Internally we use *Dfetch* for various projects and uses.
+
 
 Further Reading
 ---------------