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: update and reorganize readme.md #5513

Merged

Conversation

bmartinez287
Copy link
Collaborator

The Issue

https://github.com/vuejs/vue
https://github.com/withastro/astro
https://github.com/laravel/laravel
https://github.com/lando/lando
https://github.com/tailwindlabs/tailwindcss
https://github.com/vercel/next.js/

After looking at some popular open-source repos it seems like we could switch some items around.

How This PR Solves The Issue

This PR switches the order of certain items.

@bmartinez287 bmartinez287 changed the title docs: updated and reorganized readme.md docs: update and reorganize readme.md Nov 8, 2023
@bmartinez287 bmartinez287 marked this pull request as ready for review November 8, 2023 18:10
@bmartinez287 bmartinez287 requested a review from a team as a code owner November 8, 2023 18:10
README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Show resolved Hide resolved
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.

This is looking great and super concise, I like it.

https://github.com/ddev/ddev/blob/94080ee1b4f7f7b9b6ae518852dfd4f1153015c0/README.md

The one thing I'd ask is to move the "Wonderful Sponsors" below "Questions". I think we want people to get right to the meat and see the sponsors as they keep reading. But because it's so concise they get there just fine.

@bmartinez287
Copy link
Collaborator Author

Done.

@mattstein
Copy link
Sponsor Collaborator

If you both like this by all means run with it, but I’m struggling to understand the problem and how reordering things solves it.

The reference repos order things differently, and IMO this buries what DDEV is and how you might start doing something with it—which seem like the most urgent things to convey to someone arriving at the project.

@rpkoller
Copy link
Collaborator

rpkoller commented Nov 11, 2023

I can second matt's point. from the perspective of a person landing the first time on the project page the top tasks are what is ddev (the introductory paragraph), what are it's capabilities (highlighted features), and how do i get started (get started). but in the current version you have:

  1. introductory paragraph
  2. documentation
  3. questions
  4. wonderful sponsors
  5. contributing
  6. get started
  7. highlighted features.

For someone new to the project the point of interest, after a brief introductory teaser in point 1, starts at point 6. and i am not sure how more experienced ddev users are using the readme or if they use the readme at all since they use either ddev.readthedocs.com and/or ask on one of the socials.

@bmartinez287
Copy link
Collaborator Author

I can see that. But every project has stages, early on the get started on the readme was likely the main starting point. Now we have one on the docs, one on ddev.com and one here.
I think we might be at the stage where emphasizing sponsors and highlighting them might make more sense.
So those looking to get started have multiple ways of acquiring that knowledge but to sustain the project and achieve the goal of acquiring more full time maintainers we need to highlight sponsors more prominently in my opinion.

@bmartinez287
Copy link
Collaborator Author

Data analytics on this would be great way of testing it. But I'm not sure how that can be achieved on a repo.

We could always try it and if it does not seem to work change it back later.

@rfay rfay force-pushed the 20231108_bmartinez287_ddev_readme_reorganized branch from a964b84 to 7639a8f Compare December 15, 2023 21:18
@rfay
Copy link
Member

rfay commented Dec 15, 2023

I think it's a good contribution, at least freshening things up a bit. Followups very much appreciated.

It's easy to fuss about a contribution like this, but followup PRs with specific points will be welcome.

@rfay rfay merged commit 955065b into ddev:master Dec 15, 2023
9 checks passed
stasadev added a commit to stasadev/ddev that referenced this pull request Dec 18, 2023
stasadev added a commit to stasadev/ddev that referenced this pull request Dec 18, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants