Simplifying Drupal Documentation | bPekker.dev

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.

The Problem

concept_for_documentation.png


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.

  • 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.

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.

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.

Possible Solution: Concept and Proposal

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.
/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:

    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.

    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.
    For instance, the following guides each seem to have their own issues, in my opinion:
    Create your local environment on MacOS with Lando, following the concept above:
    To log in and start exploring, you can use the following credentials:
    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.
    mkdir my-first-drupal10-app
    && cd my-first-drupal10-app
    && lando init
    --source cwd
    --recipe drupal10
    --webroot web
    --name my-first-drupal10-app

    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.

    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:

        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!

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

        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.

        • Username: admin
        • Password: admin

    Thoughts

    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?”)

    • Similar Posts