Consolidate local development environment documentation to recommend DDEV

Created on 1 November 2023, about 1 year ago

Documentation location/URL

Opening as a tracking issue for documentation work following Recommend DDEV as the default Drupal local development environment Active .

Problem/Motivation

There are multiple different places in the handbook that talk about setting up a local development environment, some of them were originally written several years ago and don't reflect what any one does now (like XAMPP on Windows 7).

Recommend DDEV as the default Drupal local development environment Active resolved that we should recommend DDEV for new users wanting to set up a development environment, without excluding the use of other tools like Lando.

I don't know 100% what the end goal should be, but I think something like:
1. One page/section on Drupal.org for setting up a local development environment that recommends DDEV, it could also mention Lando, quickstart with PHP server and other modern alternatives so that people know they exist, but should not mention effectively defunct tools like XAMPP.

2. All other pages should either link to think to this page, or be redirected to this page, so that the documentation can be maintained in one, predictable, place.

List of pages identified as probably needing changes so far:

https://www.drupal.org/download
https://www.drupal.org/docs/official_docs/evaluator-guide

https://www.drupal.org/community/contributor-guide/reference-information...
https://www.drupal.org/community/contributor-guide/reference-information...
https://www.drupal.org/docs/getting-started/installing-drupal/drupal-qui...
https://www.drupal.org/docs/develop/local-server-setup
https://www.drupal.org/docs/develop/local-server-setup/windows-developme...
https://www.drupal.org/docs/develop/local-server-setup/linux-development...

Proposed resolution

1. Determine the local development environment page and bring it up to date.
2. Update any pages that link to setting up a local development environment so that they link to this page.
3. Generate a list of other pages for the infrastructure teams that should redirect.

Remaining tasks

🌱 Plan
Status

Active

Component

Other documentation issues

Created by

🇬🇧United Kingdom catch

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @catch
  • 🇳🇴Norway hansfn

    Minor edits to issue summary. It should be noted that DDEV is already recommended many places - added the last days. See for example

    https://www.drupal.org/docs/develop/local-server-setup/windows-developme...
    https://www.drupal.org/docs/develop/local-server-setup/linux-development...

    I'm 100% for DDEV, but I don't think that calling out XAMMP is useful. It's maintained, it actually works. IMO it's Docker solutions like DDEV compared to any manual installation of an (X)AMP stack.

    PS! The doc guide Set up a local development Drupal site on the latest Ubuntu LTS version and more (listed in the issue summary) worries me in many ways. It's like a complete Drupal Wiki inside the Wiki - see #3394693: Discuss: Set up a local development Drupal site on the latest Ubuntu LTS version and more .

  • 🇳🇴Norway hansfn

    Regarding the Evaluator guide :

    I don't think we should recommend DDEV instead of a "simple" PHP install. DDEV isn't that easy to install ... I think we tend to forget since we already have working Docker setup and more. And DDEV on Windows isn't straight forward. But it's the best tool for local development - as we already write in the Local development guide

  • 🇬🇧United Kingdom catch

    Yes I think the quickstart/php built-in webserver is a special case, but we should say something like 'once you plan to do any local development or site building, see setting up a local development environment'.

  • 🇳🇴Norway hansfn

    Yes I think the quickstart/php built-in webserver is a special case

    Good. Maybe we can strike out the evaluator guide - I add a tip in the "What's next section" of the Evaluator guide now.

  • 🇬🇧United Kingdom catch

    Also if we were to change quickstart that requires a core issue, at a minimum any changes to that should be a follow-up to this issue depending on the core one. However we might want to limit quickstart references to the evaluator guide.

  • 🇫🇮Finland lauriii Finland

    The evaluator guide steps involves either Homebrew or APT. Are we sure if that's preferred over just installing the site with DDEV using Docker Desktop?

  • 🇳🇴Norway hansfn

    Should we spin of any further Evaluator Guide (EG) discussion into a separate issue? (Installing on Windows is downloading a zip file - made that clearer in EG now.)

  • 🇬🇧United Kingdom catch

    Separate issue for evaluator guide sounds good to me.

  • 🇦🇺Australia almunnings Melbourne, 🇦🇺

    Pursuing this ticket, without first resolving concerns in the idea discussion Recommend DDEV as the default Drupal local development environment Active is disheartening.

    Community concerns around favouritism, language, variety and vendor need to be considered.

  • 🇬🇧United Kingdom catch

    @almunnings the language has already been changed multiple times based on that discussion in that issue, and at the moment there is no formal proposed text for the documentation pages at all. No-one has expressed actual concerns about DDEV itself, they have just expressed concerns about recommending one solution, and even that was based on a lot of misunderstanding about the scope of the issue.

  • 🇧🇪Belgium BramDriesen Belgium 🇧🇪

    How do we proceed with this? Do we draft the documentation in Gdocs or something? Do we create unpublished pages on D.O? :)

  • 🇫🇷France nod_ Lille

    I guess a gdoc linked in the IS to start the work and posting here as an IS update once the text is settled for validation works as a process.

  • 🇳🇴Norway hansfn

    Hm, it's a wiki and people can edit without paying any attention to this thread. Maybe using Gdoc for one central page that needs rewriting is useful, but most of the pages in the IS are already updated with info about DDEV ... I suggest making child issues for pages that need substantial editing / discussion (like we did for the Evaluator Guide). And maybe the issue summary is enough, no Gdoc needed.

  • 🇫🇮Finland lauriii Finland

    https://www.drupal.org/docs/installing-drupal/before-a-drupal-installation should probably link to one of the DDEV based instructions.

    https://www.drupal.org/docs/develop/local-server-setup is pretty hard to navigate. Wonder if this could be simplified? Might need to be split into its own issue since we might want to rethink the structure a bit.

  • 🇫🇮Finland lauriii Finland

    I'm wondering if we should update https://www.drupal.org/community/contributor-guide/reference-information... to include the exact steps needed to setup a core development environment? The fact that the current steps are documented on two different pages at the moment makes it a bit hard to follow.

    I also discovered https://www.drupal.org/docs/develop/development-tools which currently features DrupalPod.
    .

  • 🇬🇧United Kingdom rachel_norfolk UK

    Just as a note, DrupalPod is an extension of DDEV to ease contribution. I wouldn't see that changing in the docs, though it probably needs putting in better context.

  • 🇫🇮Finland lauriii Finland

    I don't think we need to get rid of DrupalPod related documentation altogether, but displaying it on the main level is not aligned with the effort to consolidate local development environment documentation on DDEV. If we want to highlight DrupalPod as an alternative way to do core development, we should put it in context with the recommended solution by explaining how it's different from the recommended solution, and why someone might choose it instead.

  • 🇩🇰Denmark ressa Copenhagen

    Ambitious Site Builders need a solid tool to build great Drupal sites with, so I think this issue could be tagged with that?

  • 🇫🇮Finland lauriii Finland

    I asked ~10 new contributors use the steps defined for DDEV in https://www.drupal.org/community/contributor-guide/reference-information... . Everyone following the steps ended up installing Drupal using composer with the original set of steps. Couple of the contributors worked on a revision of the steps based on how they would have expected it to be.

    One remaining challenge with the steps is that all of the contributors expected to be able to use Drush but I wasn't sure what are the steps to be taken to install Drush on the core development environment. At the moment, the steps recommend using Drush with composer but that's going to change the composer.json in the project directory which is not desired.

    Another challenge we discovered is that some Drupal core issues require downloading contributed modules (common for Claro related issues in particular). However, downloading modules using composer is also not possible without changes to the Git tracked files. Also, installing contributed modules on 11.x is not possible. I'm not sure if these steps are correct, but I instructed them to composer install the module in 10.2.x, install the module through the Drupal modules page, revert git changes, and finally change back to 11.x or the fork branch. This is not necessarily related to DDEV but I think the local development instructions should at least link to documentation on how these should be handled.

  • 🇬🇧United Kingdom catch

    One remaining challenge with the steps is that all of the contributors expected to be able to use Drush but I wasn't sure what are the steps to be taken to install Drush on the core development environment. At the moment, the steps recommend using Drush with composer but that's going to change the composer.json in the project directory which is not desired.

    This is what I do when I'm developing with core locally, and then I ignore the composer.json changes when I'm committing (or sometimes reset those files which still leaves drush installed until you run composer install again). @joachim has an alternative way of setting up ddev for core development, which avoids this, but which I haven't tried tbh. https://github.com/joachim-n/drupal-core-development-project

    We could also look at adding more console commands to core (for drush si/cr/en/pm-uninstall etc.) as a way to mitigate this so that drush becomes less required.

    Also, installing contributed modules on 11.x is not possible. I'm not sure if these steps are correct, but I instructed them to composer install the module in 10.2.x, install the module through the Drupal modules page, revert git changes, and finally change back to 11.x or the fork branch.

    This should hopefully become a non-issue as soon as 11.x is a 'real' branch for Drupal 11 preparation and modules start adding compatibility, which is very soon. We'll then be on the 11.x branch all the way through the 11.x minors, and the 12.x branch might never exist if we switch to main + composer aliases which ought to also resolve the problem in a different way. It's been very annoying the past six months but should be temporary and fix itself.

  • 🇩🇰Denmark ressa Copenhagen

    Also, installing contributed modules on 11.x is not possible.

    Just like theme development got a turnkey solution for disabling caching with Twig debugging / caching settings added to administrative user interface , it would be great with an "Ignore Drupal version limitations (Danger! Warning!)" checkbox under Development, to allow downloading and installing for example Admin Toolbar or Devel for Drupal 10 in Drupal 11, without jumping through any other hoops. Checking this box should override both composer.json as well as *.info.yml limitations.

    Adding the Lenient Composer Endpoint to Drupal core, with a wildcard for all Composer projects, can take care of Composer, and the *.info.yml limitation can be taken care of in Drupal core.

    Since the Drupal 10 and 11 code base will be quite similar, Admin Toolbar probably works 99.9%, see 📌 Add Drupal 11 support Needs review .

    I created the issue Allow Drupal core developers and site builders to download contrib module in the next version Active .

  • 🇳🇴Norway hansfn

    FYI: I just deleted Installing on Windows Server 2016/Windows 10 . We can't promote outdated, extremely laborious approaches to setup a dev environment.

  • 🇺🇸United States mradcliffe USA

    I asked ~10 new contributors use the steps defined for DDEV...

    One remaining challenge with the steps is that all of the contributors expected to be able to use Drush but I wasn't sure what are the steps to be taken to install Drush on the core development environment. At the moment, the steps recommend using Drush with composer but that's going to change the composer.json in the project directory which is not desired.

    This is one of the reasons why mentors recommended using a remote development environment, DrupalPod, for new Drupal core contributors for Drupal 10 at contribution events so that we could reduce the time to start contributing. DrupalPod makes use of joachim-n/drupal-core-development-project that catch mentioned above.

    This is what I do when I'm [@catch is] developing with core locally, and then I ignore the composer.json changes when I'm committing (or sometimes reset those files which still leaves drush installed until you run composer install again).

    This is what I do locally myself as well, and I think for long-term contribution, having a local environment is important.

    We could also look at adding more console commands to core (for drush si/cr/en/pm-uninstall etc.) as a way to mitigate this so that drush becomes less required.

    Several related issues:

    - #2289405: [META] Port all shell scripts to console commands (core, meta)
    - #2953810: Provide a single command to un-install after installing with single command (core)
    - #2242947: Integrate Symfony Console component to natively support command line operations (core)
    - #2894476: Provide commands which are helpful for core development (core)
    - Add drush/drush to Drupal Composer project templates Active (idea project)
    - #3089277: Provide core CLI commands for the most common features of drush (idea project)

    I added /tools page feedback to the mentor meeting to ask mentors last week and added it as a topic to the upcoming meeting in December.

  • 🇺🇸United States eojthebrave Minneapolis, MN

    One suggestion based on reading https://www.drupal.org/community/contributor-guide/reference-information... would be to add .ddev to the example.gitignore file and eliminate the need for that step in the docs.

    Another thing that might be worth considering is that there are kind of two different reasons for a local development environment; Working on Drupal core (where you need the latest git branch), and building a site using Drupal. And they're a little bit different since you're installing Drupal with a git clone of the core repo vs. Composer. And it might be worth calling that out so that it's clear which approach is recommended for someone building a site with Drupal vs. working on Drupal core.

  • 🇬🇧United Kingdom AaronMcHale Edinburgh, Scotland

    > add .ddev to the example.gitignore file and eliminate the need for that step in the docs.

    I don’t remember if it was in this issue or another one, but I saw a suggestion to ship a default ddev config specifically for core development. So for instance it has the latest supported version of PHP and MySQL/PGSQL.

    I think something like that would be useful, especially if the PHP version was regularly updated as needed, but only for Core development, so maybe that would only be included in the core-dev package?

  • 🇹🇭Thailand Nick Hope

    I am writing a new guide to installing Drupal in DDEV with the Docker CE engine in WSL2, having been through the process recently and taken extensive notes. The intention is that it will be the first guide in https://www.drupal.org/docs/develop/local-server-setup/windows-developme... .

    I'll include some steps on DDEV-Drupal configuration, but I expect/hope that info could be in a separate "Drupal in DDEV" guide linked from https://www.drupal.org/docs/develop/local-server-setup/docker-based-deve... , that applies to DDEV on any platform.

  • 🇹🇭Thailand Nick Hope

    My aforementioned guide is here: Installing Drupal with DDEV in WSL2 on Windows . It is written from the perspective of a Windows-using site builder with no Linux experience and limited development experience.

    It goes quite deep, sometimes into quite peripheral areas (e.g. Zsh), but as DDEV is now the recommended Drupal development environment, there is no escaping the fact that this environment requires some Linux command line skills, which can be daunting. It's not Dev Desktop! So I hope Windows users will appreciate the hand-holding, detail, and effort to make their experience as least intimidating as possible. This is the guide I wish I had when I undertook the process of transitioning from AMP-stack environment to DDEV myself, a process that I found quite complex and time consuming.

    Feedback welcome here or in the docs' 'Discuss' threads.

    I and others have also spent quite some time signposting various 'development environment' guides back to the DDEV-related pages, initially with warnings, but more recently with 'note-tips'.

    Guides to installing Drupal with DDEV on Mac OS and Linux are still needed within the Mac OS guide and the Linux guide . They would not need to go into the detail that my DDEV-on-Windows guide does. One-pagers would probably be enough, and this page from my guide could be a useful reference to start with. It might be quite a straightforward job for Mac/Linux users to do that, or at least get something in place that can be fleshed out.

  • 🇺🇸United States eojthebrave Minneapolis, MN

    There's also this page https://www.drupal.org/docs/official_docs/local-development-guide which walks you through the steps required to install Drupal using DDEV once you've successfully installed DDEV. Personally I think it would be best to consolidate as much of the "how to use DDEV" documentation into a single page as possible since in theory once you've got it installed for your OS of choice the using DDEV part of it should be basically the same. And there ends up being a lot of duplication if these steps are documented individually for each OS.

  • 🇬🇧United Kingdom catch

    Guides to installing Drupal with DDEV on Mac OS and Linux are still needed within the Mac OS guide and the Linux guide

    Is there a reason to write our own documentation for this as opposed to linking to https://ddev.readthedocs.io/en/latest/users/install/ ?

  • 🇹🇭Thailand Nick Hope

    Re #30, I agree that much of what I've put in the Windows guide about the DDEV & Drupal installation should probably be put into documentation that applies to all platforms.

    In practice, that would mean removing much of Installing Docker, DDEV & Drupal in WSL2 (after the WSL2-specific stuff at the top) and integrating it into Local Development Guide .

    That's quite a lot of detail to add, and some of it is a little opinionated. Is that OK? It would be a pity to lose that detail completely because I think it helps Windows users to have a step-by-step guide from start to finish so they don't get overwhelmed.

    In fact, with that much detail added, Local Development Guide may be better as a multi-page guide rather than just a page. Then, for example, the Drupal best practice settings page I wrote could also be appropriately edited and moved into it (and further modified if need be).

    Re #31, probably not, actually. I think the Windows DDEV guide was much more important than for Mac OS / Linux because of the WSL2 factor and specific considerations that introduced (like simply how best to edit text files).

    Also, I think the new recommendation that @eojthebrave has added on the Mac OS page should probably also be added to the Linux page, to focus the recommendation on DDEV.

  • 🇳🇴Norway hansfn

    I'm in the same boat as catch and eojthebrave - we should avoid duplicating / writing our own documentation for third party software and we should try to consolidate as much as possible (and not write for a specific OS). I feel kind of bad stating this because you have written a very nice piece of documentation, Nick Hope.

    PS! I have pointed out the problem with these self-contained, mega documentation guides earlier.

  • 🇹🇭Thailand Nick Hope

    @hansfn Don't feel bad. I'm also fundamentally in agreement and the work I did on that guide won't go to waste.

    I'm ready to crack on with moving some content from Installing Docker, DDEV & Drupal in WSL2 to Local Development Guide. I'm talking about, for example, the Extending DDEV section, which I think has value.

    If the consensus is that some of the new material is too much repetition of DDEV documentation (e.g. the DDEV Commands section), or too peripheral for drupal.org (e.g. the BrowserSync section), I could strip it out for d.o. and post the whole start-to-finish thing as a more opinionated tutorial offsite.

    If Local Development Guide gets too long, it looks like I could make a guide of it (rather than a page) myself and the existing page could be removed.

    Will hang on a bit to see if others have input first.

    By the way, there was some feedback on the guide from @rfay (the DDEV guy) on the DDEV Discord at https://discord.com/channels/664580571770388500/1068592266752573440/1200... Haven't followed up his points yet.

  • 🇳🇴Norway hansfn

    Yes, moving any stuff that isn't specific for Windows to a more general page is nice. And maybe you could extend the Configuring Visual Studio Code page too.

    I could strip it out for d.o. and post the whole start-to-finish thing as a more opinionated tutorial offsite.

    As you already have guessed, I think that is good solution. (Adding a link to that offsite tutorial would be OK in my view.)

  • 🇺🇸United States eojthebrave Minneapolis, MN

    I like this direction too and was going to suggest maybe Drupal.org isn't the right place for the full nitty-gritty details version and a post elsewhere that's linked to might be better. So +1. Trying to strike the right balance between I can't find the info I need because it's not here, and I can't find the info I need because it's here but buried. Which is something that varies wildly throughout the pages on Drupal.org. :)

    Thanks again for your continued effort. So awesome!

  • 🇹🇭Thailand Nick Hope

    Thanks for the feedback. I'm planning to tackle this next week.

  • 🇫🇮Finland lauriii Finland

    We should also update the local development instructions in https://www.drupal.org/docs/getting-started/installing-drupal . I was testing if I could get to the DDEV documentation from the front page without using search. This was the first page I landed on because it was linked in https://www.drupal.org/project/drupal/releases/10.2.4 .

  • 🇳🇿New Zealand quietone

    I came to this issue hoping to find some a task I could do but there are no tasks in the Issue Summary. I then skimmed the comments hoping to figure out something I could do. Alas, I could not find anything. Can someone here more familiar with the conversation here add some defined tasks to the issue summary? I apologize if I missed some actionable items.

  • 🇬🇧United Kingdom catch

    @quietone I think the proposed resolution is still current and somewhat actionable, it's just hard. We need to decide which of the current 10+ local development environment documentation pages, in which of the many documentation sections, will remain. We then need to update the content (to recommend ddev) if it's not up-to-date. At the moment, it's not obvious which one is the 'canonical' one that should remain so figuring that out is the first step.

    The links in #16 and #17 should be added to the issue summary (at least, possibly more in the issue) so we have a comprehensive list of pages to remove/redirect too.

    Once that that canonical page is identified and is good enough, all of the other documentation pages which duplicate need to be deleted/redirected so that there is a single source for the information which can be maintained/improved over time. This is likely to involve editing other areas of docs too - e.g. if they're part of a multi-step howto, then that somehow needs to incorporate referencing the canonical docs instead of duplicating it.

  • 🇳🇴Norway hansfn

    Editing link display in IS.

  • 🇪🇨Ecuador jwilson3

    I've added the links from #16 and #17 to the IS. Please note that the URL alias for /docs/installing-drupal/before-a-drupal-installation (as listed in the comment #16) has been updated since that comment was added, and moved into the "getting started" section.

  • 🇪🇨Ecuador jwilson3

    Re: #40:

    At the moment, it's not obvious which one is the canonical one that should remain so figuring that out is the first step.

    I propose docs/develop/local-server-setup as the home for DDEV.

    My reasoning:

    1. Since many pages will be linking here and we want the page to be discoverable from high-level new users, the canonical URL should be fairly short and located in a high-level folder on the URL structure. Of the URLs listed in the issue summary, the highest-level candidate I see irrespective of its actual content on page is the "Local Server Setup" page. Of course the URL and page title itself could change a little bit in order to accomodate the IA, but in general it would remain inside the /docs/develop section, which is a sensible parent location.
    2. Others have already said that this page is confusing and hard to navigate. This page and the pages that it links to in its sub-section are currently written in a way that would need a significant structural overhaul to remove legacy options anyway. The page as currently structured with various equally-weighted subpages is diametrically opposed to the purpose of this issue and must be updated, with the goal of getting to the tl;dr faster, with real actionable steps and cli commands in front of users first, and then link to secondary/tertiary/other options as subpages. Since this content overhaul would have been required anyway to comply with point #1 in the Proposed Resolution section of the issue summary (quoted below) it makes sense that this page becomes the new landing page.

      1. One page/section on Drupal.org for setting up a local development environment that recommends DDEV, it could also mention Lando, quickstart with PHP server and other modern alternatives so that people know they exist, but should not mention effectively defunct tools like XAMPP.

    The way I see the next immediate steps would be:

    • Receive feedback on proposed landing page, have others propose alternates if no consensus.
    • Write down what needs to happen to fix the information architecture.
    • Write down the plan of attack to fix the various docs' pages content to best reflect the new architecture.

    Something like this could be added to IS (if others agree).

    • Decision: Use the "Local Server Setup" node at /docs/develop/local-server-setup as the home for the top level Ddev docs page.
    • Fix the Information Architecture:
      • Update the Node title and URL alias to something even shorter. E.g. /docs/develop/ddev-local, ensuring redirects from old alias is working.
      • Move off most of the existing content of the page to another page at /docs/develop/other-local (or similar).
      • Move the menu item within the "Develop" section (eg sidenav on /docs/develop page) to the very top of the list. This is because one of the first things you think of when developing is getting your local environment setup.
      • Prioritize down the "Develop on Windows" link on the /docs/develop "Development Tools" page and instead add the link to the new Ddev docs page high on the page ideally in the "Development Tools" section.
    • Fix the docs content to reflect the new architecture:
      • Rewrite the top-level page in the most practical and brief way possible to keep the page short. Get CLI commands in front of users earlier rather than later. Avoid breaking it into sub-pages if at all possible. Decide how many "cli commands" to include. Do we duplicate content from Ddevs own Quick Start guide docs page? or link to it? https://ddev.readthedocs.io/en/stable/users/quickstart/#drupal
      • Decide if XAMPP and others should be removed or left on the "Other" page for posterity, backward compatibility, and edge cases.
      • Consider a rewrite of the "Develop on Windows" page to prioritize Ddev over the other solutions as an integral part of setting up on Windows, instead of as a kind of afterthought. Replace links to XAMPP with a link to the "Other" page.
      • Create a list of required changes ordered by complexity on the rest of the docs pages listed above (complexity levels might include: page delete, body copy overhaul, paragraph rewrite, single sentence rewrite, or link destination update, etc).
      • Execute the list of changes.
  • 🇳🇴Norway hansfn

    Some link tweaking in issue summary.

    Some random comments to jwilson3 above:

    1. "Update the Node title and URL alias to something even shorter. E.g. /docs/develop/ddev-local".
      Yes, short and nice URL aliases would be perfect, but I have been told that we should leave automatic URL aliases on - multiple times. Then the URLs tend to become very long ... Anyway, I think the use of URL aliases might need a separate issue
    2. I think we should avoid repeating information that is maintained upstream. If we can focus on what is truly Drupal specific, that helps. (The DDEV people documents installing DDEV quite nicely.)
    3. Removal and clean-up is nice, but we have to remember that this is a Wiki. People can create pages about the tools they use. This is how we ended up where we are. I don't mind being strict, but putting everything under "Other" doesn't help. We have to dare to remove stuff
    4. And finally, a rant: Installing DDEV isn't easy on Windows. That is why we get guides like this - great work, but repeats too much infomation for my liking.

    So, how do we proceed? Consensus by discussing like this takes long time. Maybe just edit the IS and discuss when we disagree ...

  • 🇺🇸United States mradcliffe USA

    Regarding /tools (or /community/contributor-guide/reference-information/quick-info/setting-up-an-environment-to-test-drupal-patches-and-merge-requests), mentors came to a consensus to continue to maintain that page with the existing options so that no-code and low-code testing and development environments are available options for new contributors.

    Once the proposed /docs/develop/local-server-setup is up-to-date or ready, then we return the local ddev instructions on /tools to a description and link. We are still working on how best to organize /tools to recommend the option most-suited for the task a new contributor is attempting.

  • 🇳🇿New Zealand quietone

    Thanks for the recent comments. It has helped.

    So, for item 1 in the proposed resolution, I read one suggestion which is to use the "Local Server Setup" node at /docs/develop/local-server-setup as the home for the top level DDEV docs page. If that is used, is the idea to add a page or a guide for the creation of docs for DDEV?

    Did I miss a suggestion? Does anyone have a place they think is better?

  • 🇬🇧United Kingdom catch

    My only concern about this being in the development guide is that it a lot of people who don't consider themselves developers would benefit from being able to run a local environment, but that's something that can done separate to this change - once we've got a single page, we can move it around in the IA if necessary. It seems like a good spot to concentrate on.

    What I'd love to see on https://www.drupal.org/docs/develop/local-server-setup is at the very top the commands to get an install running if you already have ddev installed on your computer, and a link to 'how to install ddev' for people who don't.

  • 🇺🇸United States eojthebrave Minneapolis, MN

    There's also this page https://www.drupal.org/docs/official_docs/local-development-guide which which was originally written as part of an earlier initiative to be opinionated and brief. This page is currently linked in the top level "Resources" tab in the navigation. And I think provides a good foundation for the documentation that would get someone from zero to DDEV + Drupal running the fastest with the least amount of documentation duplicated from the official DDEV docs.

    I think this page, or its content moved somewhere else, should be the page that we link to when we first tell someone to setup a local environment.

  • 🇳🇿New Zealand quietone

    Yes, the page mentioned in #48 is a good foundation to build on. Would it help to create a google doc to work on the page content?

    Thinking more about the audience which is not necessarily developers why not add a new guide to Gettins started . It wound contain a page for DDEV and leave room for other intro level information? May a page for using something like simplytest.me?

    Related the guide Installing Drupal is very develop focused so that could move to Develop .

  • 🇺🇸United States mradcliffe USA

    Thinking more about the audience which is not necessarily developers why not add a new guide to Gettins started. It wound contain a page for DDEV and leave room for other intro level information? May a page for using something like simplytest.me?

    Good point. That might help with refactoring Setting up an environment to test drupal patches and merge requests as a lot of that information is there, but the page is mean for contribution, not necessarily web site builders and developers. The short URL for that is /tools and the title of the page was more generically "Drupal Community Tools".

  • 🇳🇿New Zealand quietone

    I decided that something concrete here would help. So, I made a google doc for the 'main' page for how to install DDEV. And once we have that mostly sorted it can go to d.o, improved and cleanup on other pages can start.

    What I have done is 'how to' install DDEV and Drupal and that merely links to the very good DDEV docs.

    Can everyone make suggestion/edits there for what this new 'DDEV section' should be.

  • 🇳🇿New Zealand quietone

    To keep this moving along, I made a new page based on the google doc which didn't receive reviews.

  • 🇺🇸United States eojthebrave Minneapolis, MN

    Thanks for making the new page. I think it looks fine, though I suggest moving it higher in the Installing Drupal guide to make it more prominent as I believe the goal is to guide people to DDEV as quick as possible.

  • 🇳🇿New Zealand quietone

    Moved the page to the top of the menu.
    Started updated the pages listed in the issue summary to direct to the new page. And updated the issue summary to keep track.

  • 🇳🇿New Zealand quietone

    Where to make issues for these pages?

  • 🇳🇿New Zealand quietone

    Why does this Installing Docker, DDEV & Drupal in WSL2 say that Ubuntu needs to be installed first? In general, the whole section Installing Drupal with DDEV in WSL2 on Windows is confusing to me. It has a lot of information that is not about installing.

  • 🇬🇧United Kingdom catch

    Why does this Installing Docker, DDEV & Drupal in WSL2 say that Ubuntu needs to be installed first?

    I've never used WSL2, but my understanding is WSL2 out of the box doesn't do anything, and you have to install a linux distribution on it first, so it is recommending ubuntu to have a consistent environment within WSL2 to then carry out the rest of the steps.

  • 🇳🇴Norway hansfn

    Yes, your understanding is correct. WSL is just a virtual machine and needs an operating system (where Ubuntu is supported out of the box).

    > In general, the whole section Installing Drupal with DDEV in WSL2 on Windows is confusing to me. It has a lot of information that is not about installing.

    Yes, I have written about in other issues. Nothing wrong with the guide itself, but it covers too much - IMO.

  • 🇳🇿New Zealand quietone

    Thanks for the explanation. In hindsight I probably should have just read up on WSL2. Either way, I was able to update that page.

    covers too much

    That is exactly why I like the diataxis model.

  • 🇳🇿New Zealand quietone

    Updated more pages.

    Suggestions for what to do with https://www.drupal.org/docs/getting-started/installing-drupal/drupal-qui... ? Leave as is?

  • 🇬🇧United Kingdom catch

    https://www.drupal.org/docs/getting-started/installing-drupal/drupal-qui... is still incredibly outdated. It's talking about MacOS releases prior to 2021, Ubuntu 20.04 which is end of life April 2025, AMP on Windows etc. I would archive that too.

  • 🇳🇿New Zealand quietone

    I not sure why we should archive a page for quick-start when that command exists. I edited the page to remove the out of date references and to add a reference to development environment which directs to DDEV install page. Better?

  • 🇳🇿New Zealand quietone

    This issue can't change the download page. But the new design is eing discussed in 🐛 Feedback on Modern Drupal.org Design Active and those interested in that page should discuss it over there.

    I did make a wee comment over there 🐛 Feedback on Modern Drupal.org Design Active that the page is suggesting quick-start for developing, which is not what we want.

    Changed a sentence on docs/official_docs/evaluator-guide to direct to the new guide.

    That leaves Local Development Guide to do. Which i think of a landing page that will point me to the pages with key information to get started as a developer. Therefore I suggest a replacement of these sections, which are 'how tos',

    • Local development with DDEV
    • Configure your local development environment to serve your application
    • Create a new Drupal application
    • Install Drupal
    • Log In

    with a link and some text directing to the new page, https://www.drupal.org/docs/getting-started/installing-drupal/install-dr... .
    What do you think?

  • That is exactly why I like the diataxis model.

    The link appears to be a 404

  • 🇬🇷Greece TheodorosPloumis Greece

    Here is the Diataxis technical documentation model: https://diataxis.fr

  • 🇳🇿New Zealand quietone

    I have fixed the link in comment #62.

    @ressa, nice improvements on the Evaluator guide.

Production build 0.71.5 2024