Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Debug environment variable suggestions #4949

Merged
merged 4 commits into from
May 23, 2023

Conversation

mattstein
Copy link
Sponsor Collaborator

@mattstein mattstein commented May 23, 2023

The Issue

I didn’t get a chance to review

  • It’s best to reiterate in every case, provided it doesn’t interrupt the reading flow, that commands are meant to be run. This is especially true when someone’s troubleshooting and we want them to be successful without knowing their technical comfort level with what’s going on.
  • A callout was added with a heading that didn’t summarize the contents as much as label them, and it gave excessive emphasis to something that...
    • a) From its own language, is less useful to everyone and meant for DDEV developers.
    • b) Appeared ahead of, and thus took attention away from, another callout more broadly applicable to a beginner troubleshooting. (Stacking callouts is usually indicative of a flow problem with too much noise.)
    • c) Includes material for a different audience; existing troubleshooting steps seem careful and beginner-friendly, and this callout talks about a Dockerfile build process that abruptly assumes a different level of prerequisite knowledge—with no qualifying introduction or explanatory language.

How This PR Solves The Issue

This PR refines the newly-added docs and moves the callout into a subsection.

This doesn’t fix the audience-shift problem (c), but it moves the callout to a subheading in that first section, with a concise heading to describe what it covers. It also rewords the contents of the callout to topically introduce the environment variables with gentler context that’s hopefully just as accurate.

Manual Testing Instructions

Preview changes locally or inspect the automatic build:

Automated Testing Overview

n/a

Related Issue Link(s)

#4919

Release/Deployment Notes

n/a

@mattstein mattstein self-assigned this May 23, 2023
@mattstein mattstein marked this pull request as ready for review May 23, 2023 14:35
@mattstein mattstein requested a review from a team as a code owner May 23, 2023 14:35
@mattstein mattstein requested review from rfay and removed request for a team May 23, 2023 14:35
Copy link
Member

@rfay rfay left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks so much for this. Looks reasonable to me.

@mattstein
Copy link
Sponsor Collaborator Author

Please merge at whatever moment brings the most joy.

@rfay rfay merged commit 52d8c65 into ddev:master May 23, 2023
10 of 11 checks passed
@mattstein mattstein deleted the docs/4919-suggestions branch May 23, 2023 23:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants