Improve “Get Started” page

[mattstein]

Make it impossible to get lost and reduce the need to jump away.

• Make it more visual, possibly with the ability to select a platform all steps can follow.
• Provide simple, concrete steps for the user to follow (with no alternate options or decision points).

Per 1/9 discussion in Discord, we should carefully consider a CMS-agnostic start so we don’t lose people thinking DDEV only supports specific CMSes.

[mattstein]

@rfay I got just enough done in a941962 that you can see what I’d like to do in the preview build:

• Starts with OS selection (with lightweight auto-detection) so the remaining instructions can be specific and easier to follow.
• Uses a simple terminal style to convey that we’re looking at terminal actions (not code), and in some cases responses—like getting a Docker or DDEV version back.
• Uses sparing tabs so you can choose your own adventure with minimal impact on flow.
• It’s written roughly the same, but includes all critical instructions so the reader only needs to click away if they want to learn more but not to actually install and use DDEV.

Our new analytics indicate lots of pressure on this page, so it should be really helpful to take it from something a bit stale to the most carefully-tailored “first look” content.

The Windows and Linux instructions obviously need to be fleshed out, but happy to hear whatever you think!

[mattstein]

There’s some gross stuff happening here with typography like weird spacing around links and <code> blocks, and like everything here the layout needs work—so try to ignore the gnarly bits.

[rfay]

That's looking mighty fine, has loads of potential.

• I'm a little worried about the ease of maintenance of https://github.com/drud/ddev.com-front-end/blob/main/src/pages/get-started.astro - at first glance it looks like some knowledge is required to maintain.
• It obviously would have to be maintained in parallel with the docs; I imagine you'd like to have the "get started" looking just like this in the docs to make things easier in general. I know you've thought deeply about that, but it's a concern.

[mattstein]

I'm a little worried about the ease of maintenance

The code's still a mess but I'd refactor it to something less cumbersome (and more HTML-like) before calling it finished.

I imagine you'd like to have the "get started" looking just like this in the docs to make things easier in general.

Ideally, but not anytime soon.

1. The docs are on a different platform that to me is less malleable. Doing the equivalent there is a pretty different scope of work.
2. I wouldn't copy this word for word because it's a standalone page focused on quick setup with minimal context, where the docs are a larger body of organized content that can and should be more self-referential. (Car test drive vs. owner's manual.) It would need to be kept technically accurate, but it doesn't serve the same purpose.

[mattstein]

An example of #2 is omitting Colima, which could be controversial but it seemed like the methods I chose were the fastest and simplest. The goal of the page is not to be thorough, but quick and clear for someone willing to give their attention to trying DDEV.

[mattstein]

If maintainability is still a concern, we could vastly reduce the scope of this page and use it to describe requirements/expectations and punt to Getting Started in the docs.

I think as planned this page does something uniquely important, but I understand if it's not worth the cost of upkeep or risk of becoming stale.

[rfay]

I think it's going to be great, and I can learn to maintain it, as long as there are no significant booby traps in there. It's going to be great.

How will we be able to sort out what's maintained on the back-end site (blogs) and what's markup in the front-end?

[mattstein]

How will we be able to sort out what's maintained on the back-end site (blogs) and what's markup in the front-end?

I’ll clean up, document everything within the code and more broadly about the setup, and follow through with tasks like this to make sure we don’t have misleading stale content hanging around.

The code you’re seeing now is not very well organized or commented, just a mess of me thinking and quickly roughing out components. In a more shippable form it’ll be less chaotic and better labeled. :)

Generally though, the src/pages/*.astro files are like HTML pages with superpowers. The src/pages/blog/[*].astro files are slightly fancier since they’re building routes+pages with external content, but it’s not that far a stretch. Happy to walk through this at any point!

[mattstein]

...and if the WordPress connection is adding more complexity than benefit, we can still migrate those posts to Markdown so everything lives in this repository as @mayankguptadotcom suggested. I’d need to rewire some things and obviously migrate all the existing posts, but happy to do it if it’s better in the long run and we don’t need the WordPress install.

[mattstein]

Coming along slowly, but more progress.

I realized one of the easiest ways to try DDEV may be with one of the cloud providers, so I renamed that first selector and added a “Cloud” option:

And while it could be overboard, I updated the terminal wrapper so it could look more at home for whatever platform is selected.

Mac:

Windows:

Linux:

While this could be gratuitous decoration, it may be useful to reiterate which terminal Windows users should be working in. I may be the only person that’s struggled with that in the past, but I doubt I’m alone there.

[rfay]

that's amazing :)

[mattstein]

The current iteration of this page is ready for scrutiny, with emphasis on the Windows and Linux instructions being as accurate, prescriptive, and concise as possible—which explains some very specific recommendations and omissions if you’re comparing to the Docker installation and DDEV installation pages where thorough is more important than quick.

I refactored the source so editing individual instructions is less cumbersome, with blurbs separated out here: https://github.com/ddev/ddev.com-front-end/tree/main/src/components/quickstart

Open questions (by order of importance):

1. Is there anything that’s inaccurate?
2. Is there anything that’s vital and missing for a newcomer wanting to try out DDEV immediately on their platform?
3. Is there anything that can be cut out or made simpler?
4. Are there any UX improvements that could reduce friction?

Examples of item 4 that are built in:

• Automatic OS detection, so the most relevant tab can be pre-selected
• Support for URL hashes, so someone could share https://ddev.m7n.io/get-started#windows to be more specific when relevant.
• Subtle fake terminal styling that can visually reiterate wherever you’re running commands.
• Built-in fetching of the latest DDEV release version for terminal examples, which will more likely match what someone sees trying this out. Demonstrated in ddev -v examples. (Dependent on site’s exact build date.)

One UX improvement would be the ability to easily copy the first line out of a given example—without the → or > or $—to run locally.

[mayankguptadotcom]

Oh, this is amazing. I'm sorry guys that I've not been able to spend the time that I want to. I've been caught up in multiple things on my end. I'm getting a grip on all those and should be able to start getting active very soon. thank you @mattstein & @rfay as always for all that you guys are doing to keep #DDEV going upwards!

[rfay]

This is stupendous work, and far above and beyond the call of just "getting ddev.com under control"! Wow. What a labor of love and what a great improvement.

• Automatic OS detection didn't work for me (on macOS) but it's OK...

• macOS: After you install Docker Desktop via homebrew, you have to start it and accept license agreement etc before proceeding. It's worth saying to start it up.

• macOS (sidenote) I'm not absolutely convinced that Docker Desktop is easier to get started with than Colima, but choosing one is great.

• macOS: brew install drud/ddev/ddev is already brew install ddev/ddev/ddev, works fine. Also, installing that would result in v1.21.4 at this moment, and v1.21.5 in a week or so; I don't think displaying an alpha1 is a great thing to show, people who know that it means a prerelease may be concerned. (The alpha1 version also shows up in several other places, and v1.21.5 would be better to show there I'd think)

• wsl2: Best to say "administrative PowerShell v5 terminal" everywhere, nearly everything needs to be done that way.

• wsl2: Is it clear that creating a project is being done in Ubuntu terminal?

• everywhere: I don't think it's clear how you look at the project. ddev launch or "use browser to visit the URL given by ddev start" may help here.

• Linux: Installing docker on non-Ubuntu probably doesn't need to be pursued. So few people do that, and the ones that do can find their way in the docs.

• Linux: We prefer people to use apt install, not the script, they'll be happier in the end. It's not hard. (In general, I'd rather people don't use the script any more, although it will continue to be maintained, but there aren't any significant places where it's needed these days.)

• gitpod: apt install is preferable to brew install

• both gitpod and github codespaces: There is a bunch of missing context there (config/start/launch/describe/stop) that is in many other places. People probably don't know what to do.

It's all great stuff, amazing effort, congratulations and thanks! Sorry so slow to look at it.

[mattstein]

Thanks for reviewing this! I’ll tackle the more straightforward updates. Sounds like there are a few more things to figure out, though.

⚠️ I wrote a lot below, but I’m happy to chat instead if this feels like a word bomb!

Automatic OS detection didn't work for me (on macOS) but it's OK...

Not sure why that would be, but the fallback is deliberately a prompt for selection so the reader likely won’t even know anything went wrong.

What browser were you in, if you don’t mind saying? Safari and Firefox auto-detect fine for me on macOS, but I’m just noticing Chrome does not.

macOS (sidenote) I'm not absolutely convinced that Docker Desktop is easier to get started with than Colima, but choosing one is great.

I haven’t spent equal time with each one so I’m biased toward a relatively painless experience with Docker Desktop. Even still, when I look at the installation instructions there is vastly more explanation and decision-making to get through Colima setup compared to Docker Desktop:

I’m not sure if one is any easier than the other, but one clearly represents a quicker path to me and that’s why I chose it. (Same with the Linux install script situation you called out.)

If I’m just plain wrong, and a Colima start would give the reader less to think about and a quicker path to having DDEV running on their machine, we should switch. If it takes more consideration or more steps, I’d stand by Docker Desktop. (We already seem to agree that picking one in this context is important.)

brew install drud/ddev/ddev is already brew install ddev/ddev/ddev, works fine.

This is a bug and a feature! I assume all drud/ddev references will need to become ddev/ddev before this launches, most of which will be fixed updating these project constants.

The only reason I haven’d done that yet is that the site makes GitHub API calls to fetch repo details, contributor+sponsor stats, etc. and I don’t want to break them.

Also, installing that would result in v1.21.4 at this moment, and v1.21.5 in a week or so; I don't think displaying an alpha1 is a great thing to show, people who know that it means a prerelease may be concerned. (The alpha1 version also shows up in several other places, and v1.21.5 would be better to show there I'd think)

One of those API calls is to get the latest tagged release, which you’ll see as a variable in these instructions. I thought it’d be nice to show the reader what they should be seeing in most cases without having to hand-update Markdown every time there’s a new release.

We can probably adjust the part that fetches the latest release version to only favor stable releases.

wsl2: Best to say "administrative PowerShell v5 terminal" everywhere, nearly everything needs to be done that way.
wsl2: Is it clear that creating a project is being done in Ubuntu terminal?

These two comments go together, I think. I followed the exact steps in exactly the terminals called out: PowerShell, PowerShell, administrative PowerShell, then Ubuntu through to the end. Not saying I was right or doing it in an ideal way, but it worked for me and I think transitioning to the Ubuntu terminal and sticking with it to the end (with visual reinforcement) should be pretty clear.

I’d like to know:

1. Is it best to use an administrative PowerShell terminal for every single one of these steps? (I think it’s overkill for some, and I also imagined it’d be best to stick to the Ubuntu shell and be able to use ~/ for project paths—but I barely get by with this setup.)
2. Is someone new to these instructions sure of what terminal to use in each step, or is it unclear?

Linux: Installing docker on non-Ubuntu probably doesn't need to be pursued. So few people do that, and the ones that do can find their way in the docs.

Are you sure it’s worth cutting those out? We would need to clarify that the Linux instructions really just apply to Ubuntu so nobody’s misled, and we’d be sending them on a separate adventure which is the exact opposite of the intent of this page. Linking to each distro’s Docker instructions and distilling them to their simplest form felt like it might have been useful and live up to the promise of supporting Linux installs in general.

Linux: We prefer people to use apt install, not the script, they'll be happier in the end. It's not hard. (In general, I'd rather people don't use the script any more, although it will continue to be maintained, but there aren't any significant places where it's needed these days.)

I originally started with tabs that followed the Linux install page headings: Debian/Ubuntu, Fedora, Red Hat, etc. (where the “etc.” gives me pause), and Arch Linux. The instructions still felt clunky and the headings didn’t neatly match the Docker install tabs in the section above, and it looked like the install script was the most straightforward route for anyone to take. I put a prominent note about using the distro’s package manager there so nobody feels bamboozled if they would’ve preferred to do it that way.

Is it possible to go back to something like Ubuntu, CentOS, Debian, and Fedora? Or tabs that are consistent with the “Install Docker” step? (We can’t very well start with only Ubuntu there and then continue with several distros when it comes to DDEV.)

both gitpod and github codespaces: There is a bunch of missing context there (config/start/launch/describe/stop) that is in many other places. People probably don't know what to do.

That’s my fault! 😅

I didn’t want to give bad instructions that weren’t useful, so I cut a lot out. I’ll test each one with the “Create a Project” and “Explore & Enjoy!” from other sections. Is it still just as useful to uninstall from these cloud options?

[rfay]

Let's do talk it through! If you have time I could do it now.

[mattstein]

@rfay and I did chat through everything, and I’ve finished updates to this page we agreed to tackle:

• Fixed automatic browser detection for macOS + Chrome.
• Updated drud/ddev references that could safely be ddev/ddev. (Will catch the rest later.)
• Made sure latest stable release version is grabbed by default.
• Subtly improved prompt symbols to be more visually muted and avoid text selection for easier copying.
• Added missing summary and documentation link to the beginning of the Linux instructions.
• Switched Linux instructions to use respective package managers and not the install script.
• Added “Launch Docker Desktop” instruction for macOS.
• Updated Gitpod instructions to use apt instead of brew. (Same as Ubuntu.)
• Added ddev launch step to finish out setup.
• Fleshed out Cloud instructions.

I posted an outstanding question here, but this effort should be finished unless anything needs further attention.

Closing, but please comment or open a new issue if I missed or bungled something!