Simplifying Drupal Documentation | bPekker.dev

Are you new to the world of Drupal, eager to dive into its powerful capabilities, but
encountering obstacles in the form of outdated tutorials and confusing documentation?
You’re not alone. Beginning your Drupal journey can feel like navigating uncharted
territory, leaving many feeling frustrated before they even begin.

The Problem

It often starts with the tutorials provided on Drupal.org. While these aim to
guide beginners through the process of setting up and using Drupal, they often fall short
of delivering a smooth experience. There are outdated instructions, conflicting
information, and a lack of an actual, recommended step-by-step guidance that one could
follow.

For instance, the following guides each seem to have their own issues, in my opinion:

• Installing Drupal –
  While the first chapter advises using one of the recommended Docker-based solutions,
  it only offers links to various quickstart guides without providing clear, concise
  instructions. As a result, users are left to navigate multiple sites in search of the
  necessary information, making it difficult to gather just the prerequisites. Installing
  Drupal should not be that hard, and the process should be more straightforward.
• Drupal User Guide – While the
  guide offers a thorough explanation of Drupal site building, it lacks the interactive
  experience of navigating through an actual Drupal site. As a result, it primarily serves
  as a valuable resource once you already have Drupal installed. Without that, reading
  through the documentation may not provide the full understanding of its functionality.
• Docs – The documentation includes references to
  multiple guides, such as the ‘Installing Drupal’ guide mentioned earlier, which we’ve
  identified as lacking clarity. The guides listed here span various levels of expertise
  covering topics from site building to development tasks. The structure may not
  be well-suited for beginners, as it lacks clear progression for someone who is just
  starting out.

Of course, you could opt for the one-liner from the download page to create the Umami
demo site, but if your goal is to truly understand Drupal, taking the shortcut might
leave you feeling like you missed the whole show, not to mention you need PHP and Composer for it to work.

For someone with no prior knowledge of the platform, choosing which guide to follow
can be challenging, and make this seemingly simple task feel daunting. Also,
investing time in a process that should be as simple as making toast might leave
you questioning if you accidentally signed up for a crash course in rocket science
instead!

Possible Solution: Concept and Proposal

What’s essential is a beginner-friendly, comprehensive guide — a single source of truth
— that provides clear, step-by-step instructions for installing Drupal on your computer,
from start to finish. However, it’s not just about having the right instructions. It’s also about providing
newcomers with the tools they need to succeed. This is where the Drupal community can
step in and make a real difference.

Lately, some experienced developers are taking their knowledge for granted. It’s all
too easy to forget the challenges we faced when we were first starting out with Drupal
and to overlook the struggles of newcomers.

For example, how can you expect your sales team to effectively promote Drupal over other CMS solutions
if they lack insight into Drupal’s capabilities? Moreover, how can you address the
inconvenience of developers needing to attend sales meetings to provide answers for
stakeholders? While one solution might involve providing the user guide to your sales team
and encouraging them to read it, the reality is that they may not prioritize doing so.
Even if they do, they won’t gain the same level of expertise as someone who actively
navigates through Drupal, exploring the connections between custom content types and
views firsthand. Sales representatives could more effectively sell products they
understand.

The structure of the SSOT

First, we need audience identification, to provide clear sections for both newcomers
and developers, guiding them through the process of getting started or delving deeper
into development aspects.

Once we identified the target audience (and we are targeting the newcomers in this post,
therefore we are not describing the other parts), we can create the most easy, step-by-step
guide by providing tools and commands to install drupal on a local computer.

As one can see, there are already some recommendations present in both the current
documentation on Drupal.org’s docker-based tutorial and the proposed concept above.
However, this presents a challenge as it lacks a straightforward solution, leaving
the task of deciding between options like Lando or DDEV, which can be overwhelming
without prior experience. (“Am I choosing the right one?”)

If the Drupal community were to take a more decisive approach and collectively opt
for one of these solutions, we could establish a streamlined process that guides
users through a step-by-step local Drupal installation.

The primary question at hand is: Who bears the responsibility for making that decision?

Example

Create your local environment on MacOS with Lando, following the concept above:

1. Prerequisites (Tooling and environment)
   • Install Homebrew
     Open your terminal by pressing “Cmd+Space” to open
     Spotlight search, and typing ‘Terminal’ then hitting return. Then, copy
     and paste the following script and hit enter:

     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

     The script will start to download Homebrew, which is a package manager for macOS.

   • Get PHP
     For the next part, we’ll need PHP, so use the Terminal again, and the previously
     downloaded homebrew to download PHP with the following script:

     brew install php

   • Get Composer
     In your Terminal, copy and paste the following to download Composer, which is a dependency
     manager for PHP:

     php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
     php -r "if (hash_file('sha384', 'composer-setup.php') === 'dac665fdc30fdd8ec78b38b9800061b4150413ff2e3b6f88543c636f7cd84f6db9189d43a81e5503cda447da73c7e5b6') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
     php composer-setup.php
     php -r "unlink('composer-setup.php');" 

   • Download OrbStack
     Using your Terminal and Homebrew again, install OrbStack to be able to run Docker
     containers:

     brew install orbstack

     Once installed, you should open it the same way you are opening the Terminal, with spotlight search (CMD+Space). There is nothing else you need to do, we just need it to run in the backgorund.

   • Install Lando
     Install the local development environment tool called Lando, which is built on Docker, and will help us
     create our docker-based Drupal installation:

     brew install --cask lando

2. Download and Install Drupal (Installation Script)

   • Run the following commands after each other in your Terminal

     mkdir my-first-drupal10-app 
       && cd my-first-drupal10-app 
       && lando init 
          --source cwd 
          --recipe drupal10 
          --webroot web 
          --name my-first-drupal10-app

     lando composer create-project drupal/recommended-project:10.0.x-dev@dev tmp && cp -r tmp/. . && rm -rf tmp

     lando start

     lando composer require drush/drush

     lando drush site:install --account-name=admin --account-pass=admin --db-url=mysql://drupal10:drupal10@database/drupal10 -y

     lando start

     At the end, you should be provided with some URLs, on which you can reach your installed, locally running Drupal site.

     To log in and start exploring, you can use the following credentials:

     • Username: admin
     • Password: admin

Thoughts

First of all, I don’t want to discourage those updating the guides; they are doing an
awesome work, and I truly appreciate their efforts, which reflect the spirit of the
open-source community. My focus is solely on enhancing the existing guides to draw more
people to Drupal, without causing offense to anyone in the process. I strongly believe small adjustments
such as these, coupled with initiatives like the Project Browser and Automatic Updates,
have the potential to make Drupal bigger and more impactful than ever before.