10000 Update README.markdown by noniagriconomie · Pull Request #13595 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Update README.markdown #13595

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.

Sign up for GitHub

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

Jump to bottom
Closed
wants to merge 2 commits into from
Closed

Update README.markdown #13595

wants to merge 2 commits into from

Conversation

noniagriconomie
Copy link
Contributor

Hi, a small documentation readme upgrade

I also think it could be good to create a pattern for all readmes arround main sf repos (as a brand)

feel free to close/improve if needed

cheers :)

@javiereguiluz
Copy link
Member

I agree with some of the proposed changes ... but not with some important ones.

This change for example:

image

Before it was a bit plain and boring ... but it was clear that this repository is "Symfony Docs" and not "Symfony".

Not it'd look like the Symfony repo, which is confusing ... and the "Website" link doesn't link to "Symfony Website" but to "Symfony Docs page" ... so it's confusing too 🤔

@wouterj
Copy link
Member
wouterj commented Apr 27, 2020

Oh, I like this a lot :)

@javiereguiluz please note that the centered logo is also used on e.g. the Symfony Flex repository: https://github.com/symfony/flex I think, if use it more across all readme's, that it becomes more a brand signature than "code repository" signature.

What do you think about changing it to this?

image

<p align="center">
  <a href="https://symfony.com/doc/current/index.html" target="_blank">
    <img src="https://symfony.com/logos/symfony_black_02.svg">
  </a>
</p>

<h3 align="center">The official Symfony documentation.</h3>

<p align="center">
    <a href="https://symfony.com/doc/current/index.html">
      Online version
    </a>
    <span> | </span>
    <a href="https://symfonycasts.com">
      Screencasts
    </a>
    <span> | </span>
    <a href="https://symfony.com/doc/current/contributing/documentation/overview.html">
      Contributing
    </a>
    <span> | </span>
    <a href="https://github.com/symfony/symfony">
      Code repository
    </a>
</p>

@noniagriconomie
Copy link
Contributor Author

Yes it was at first to put the sf logo like others main ones (sf/cli /flex etc) => more branding repo

The way that logo are already existing and stored, i used the same one, maybe someone can/could create with the word « doc » or « documentation » inside the image

That being said, while doing it, i added sf cast link because i think it is valuable as en entry point main documentation, maybe other links can leave here too

Thx

@noniagriconomie
Copy link
Contributor Author

@wouterj I've done like you suggested
just for the Code repository part, should the link point to the sf/sf or sf/sfdoc?

@dbrumann
Copy link
Contributor

just for the Code repository part, should the link point to the sf/sf or sf/sfdoc?

I really like it 👍 but had the same question when looking at the change.

I think linking to symfony/symfony makes more sense (as this document lives inside symfony/symfony-docs anyway, so a link feels a bit self-referential to me) but maybe change the label to "Symfony Code Repository" or just "Symfony Code/Repository"?

@noniagriconomie
Copy link
Contributor Author

Maybe adding both ? I do not know for my part, maybe must not overcharged the page

@javiereguiluz
Copy link
Member

I'm still completely against this proposal 😐

In my opinion it introduces many issues.

First, in this design, the red squares are the only things users will see (the line about "Hey, these are Symfony Docs" will be missed by most people):

image

Second, in this line there are many things that can be confusing too:

image

@noniagriconomie
Copy link
Contributor Author

@javiereguiluz

I'm still completely against this proposal 😐

perhaps because there are a lot of changes here indeed
maybe those can be done alone: add the logo (sf brand repos imo should have, for the main one (/symfony /symfony-docs /skeleton /cli ) the same readme header)

Second, in this line there are many things that can be confusing too:

yes it is the discussion here #13595 (comment) we should discuss, my main goal was to add a link to sfcast because it is very usefull but I agree there are similar links that can confuse

for the first part the red squares, maybe design a logo with the word doc into it?

@wouterj wouterj closed this May 22, 2020
@wouterj wouterj reopened this May 22, 2020
@wouterj
Copy link
Member
wouterj commented May 22, 2020

Sorry, wrong button.

In the end... how important is the README to discover the repository?

I mean, you've gone to symfony/symfony-docs, the GitHub description says "The Symfony documentation https://symfony.com/doc", you need to scroll a significant amount (without seeing any .php file) to the README contents and then you'll see the Symfony logo. Nothing here tells me I'm looking at the code repository... and why would I try to find the PHP source code here?

Besides this, as mentioned before, there are more repositories showing the Symfony logo (such as Flex) - it's a brand, not an indication of PHP code.

@noniagriconomie
Copy link
Contributor Author

hi @wouterj @javiereguiluz

as mentioned at first in the PR description

What do you suggest, after our discussions, for each points?

  • symfony logo display ? yes|no (I vote yes as a main entry point of the sf community, as much as the code repo and the cli one)

  • rephrase some parts

    • may be discussed unitary?
    • maybe remove the "Contributing" and "Code Repository" bellow the logo at first?

  • adding direct link to symfony cast ? yes|no (I vote yes because it is very tied IMO)

I then can rework or close and reopen smaller ones

thank you

@noniagriconomie
Copy link
Contributor Author

friendly ping @wouterj @javiereguiluz :)

@wouterj
Copy link
Member
wouterj commented Dec 7, 2020

symfony logo display ?

I would say yes. The latest Symfony project also has this, so it's becoming more and more "on brand" to do this: https://github.com/symfony/ux

maybe remove the "Contributing" and "Code Repository" bellow the logo at first?

I would remove the "contributing" header (it's fine not to start with a header) and remove the "Code repository" link.

adding direct link to symfony cast ?

I would say yes

@nicolas-grekas nicolas-grekas deleted the branch symfony:master December 7, 2020 16:34
@nicolas-grekas
Copy link
Member

This PR has been closed because the master has been removed.
Please submit it again against the appropriate branch.

@noniagriconomie noniagriconomie mentioned this pull request Dec 8, 2020
Merged
@noniagriconomie noniagriconomie deleted the patch-3 branch December 8, 2020 09:52
OskarStark added a commit that referenced this pull request Dec 8, 2020
@OskarStark
minor #14675 Improve README (noniagriconomie)
4d256ff 
This PR was merged into the 4.4 branch.

Discussion
----------

Improve README

Hi, this PR replaces #13595

@wouterj @javiereguiluz i have done what was decided on the other PR
Feel free to edit this PR to match "in a brand way" all the other repo readme entrypoint

Thanks

Commits
-------

9408dd8 Improve README
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
Status: Needs Review
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
6 participants
@noniagriconomie @javiereguiluz @wouterj @dbrumann @nicolas-grekas @carsonbot
0