Skip to content

Reorganize intro section on main page #16226

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

Merged
merged 1 commit into from
Jan 30, 2020

Conversation

timhoffm
Copy link
Member

PR Summary

Trying to be less verbose than the original text.

Preview:

grafik

Contents and design may still be improved, but IMHO this is a good first shot. Of course, suggestions are welcome.

Would go with 3.2.0 if we can make it, but not a blocker.

Closes #16114.

@timhoffm timhoffm added this to the v3.2.0 milestone Jan 14, 2020
@@ -35,19 +32,40 @@ interface toolkits.
</div>
<span class="clear_screenshots"></span>

Matplotlib tries to make easy things easy and hard things possible. You
Copy link
Contributor

Choose a reason for hiding this comment

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

I personally really like this sentence (yes, this specific wording) and would be sad to see it go -- it really embodies the matplotlib philsophy to me ("making hard things possible" is what distinguishes matplotlib from many "simpler" wrappers, and "making easy things easy" means that you don't have to fiddle with the GUI toolkit and that you can output to a bunch of formats natively, as opposed to e.g. web-only (js) libs).

Copy link
Member Author

@timhoffm timhoffm Jan 15, 2020

Choose a reason for hiding this comment

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

I understand your point. I've thought for a while if I should keep this sentence.

TL;DR I don't think the sentence is helpful or even suitable. But if people are attached to it, I would be willing to leave it in for now.

I have three issues with it:

  • "Matplotlib tries to ..." is too defensive. In a philosophy you don't try. If anything this would need to be

    Matplotlib makes easy things easy and hard things possible.

  • Easy and hard things are highly vague and subjective.

    "making easy things easy" means that you don't have to fiddle with the GUI toolkit and that you can output to a bunch of formats natively, as opposed to e.g. web-only (js) libs

    is your particular interpretation and focused on the output aspect.
    I've read it more broadly as "Things that I can easily describe should be easy to code."

    In it's generality, you could apply the statement to a lot of software (It appears to coined on the design of Perl). It's not a distinctive feature of matplotlib. I assume that most of the visualization libraries would claim that paradigm (with different interpretations of easy and hard).

  • From a user perspective, IMHO we are not regarded as particularly easy for various reasons. It's partly because we see core matplotlib as fundamental building blocks, and we have a limited number of high-level helpers to arrange them. This is a design choice, which is perfectly fine. I just don't think we should over-emphasize easy.

    It's not easy if I need several lines of code to make a simple plot with axes labels, title and legend. It's not easy if I have to calculate positions for grouped bar charts. There are higher-level libraries that can claim "easy" much more.

Therefore, instead of "easy things easy and hard things possible", I hope to covey the two aspects more clearly and accurately with:

  • Easy creation of numerous standard plots
  • Customizable and extendable

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm not going to try to argue rationally here -- it is strictly a sentimental attachment to this sentence. On the other hand, now that I stated my point, I'm not going to block its removal if there's agreement to do so.

(FWIW "Matplotlib makes easy things easy and hard things possible." is fine with me too, or perhaps "aims to ...".)

Copy link
Member

Choose a reason for hiding this comment

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

I'm with @anntzer on this - "Matplotlib makes easy things easy and hard things possible" is the brand/mission/ideal. And yes many users may not agree that we make easy things easy but this is the sales pitch. I think your text with some copy editing underneath works as an explanatory thing.

Copy link
Member Author

@timhoffm timhoffm Jan 15, 2020

Choose a reason for hiding this comment

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

Ok, I would like to talk about the misson statement (and also this catch phrase) at some point. It is valuable to clarify that for ourselves and also to communicate it. - Will likely be a paragraph or two on a dedicated page.

For now, I've added the easy sentence back in.

@story645
Copy link
Member

Don't have time to review this yet, but please don't merge 'til I can review 'cause there's a lot of branding/comms stuff involved in the front page and I want to stay consistent in messaging.

Copy link
Member

@NelleV NelleV left a comment

Choose a reason for hiding this comment

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

I think this looks great! It's a big improvement on what currently exists.

I'm 👍 on merging.

As a side note, improvements can be done later, specially if this doesn't make it in the next release.

@timhoffm timhoffm force-pushed the doc-overview branch 2 times, most recently from 0cb6b38 to 5d4977f Compare January 15, 2020 23:19
Copy link
Contributor

@anntzer anntzer left a comment

Choose a reason for hiding this comment

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

looks good, but I think @story645 wants more time on this?

Copy link
Member

@jklymak jklymak left a comment

Choose a reason for hiding this comment

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

This seems like an improvement and I prefer to paragraphs that say the same thing.

A few places the wording is a bit verbose. You may want to avoid phrases like "supports your tasks", or, if we want to be super chatty, embrace it more fully.

@timhoffm timhoffm force-pushed the doc-overview branch 2 times, most recently from fa515cb to 7f3bf7a Compare January 16, 2020 22:06
@jklymak
Copy link
Member

jklymak commented Jan 20, 2020

A few nits about the formatting here:

FrontPage

These boxes are the same color as the sidebar box, but do not have a blue border. Suggest they could have the blue border....

I also would suggest the headings be made bold like <h2> to be consistent with other headings that have the same font size. Note 100% sure they should be centered either, but...

Copy link
Member

@story645 story645 left a comment

Choose a reason for hiding this comment

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

Don't mean you have to make the changes I request, just don't want this to be merged w/o discussion.

@timhoffm timhoffm force-pushed the doc-overview branch 2 times, most recently from bc09d92 to 2413293 Compare January 25, 2020 14:01
Copy link
Member

@story645 story645 left a comment

Choose a reason for hiding this comment

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

Thanks for the back & forth and all your work on this PR. 😄

@story645 story645 merged commit e4dbf4e into matplotlib:master Jan 30, 2020
@lumberbot-app
Copy link

lumberbot-app bot commented Jan 30, 2020

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

  1. Checkout backport branch and update it.
$ git checkout v3.2.x
$ git pull
  1. Cherry pick the first parent branch of the this PR on top of the older branch:
$ git cherry-pick -m1 e4dbf4e7b5241e7d74f79adc854f84a954b45e8f
  1. You will likely have some merge/cherry-pick conflict here, fix them and commit:
$ git commit -am 'Backport PR #16226: Reorganize intro section on main page'
  1. Push to a named branch :
git push YOURFORK v3.2.x:auto-backport-of-pr-16226-on-v3.2.x
  1. Create a PR against branch v3.2.x, I would have named this PR:

"Backport PR #16226 on branch v3.2.x"

And apply the correct labels and milestones.

Congratulation you did some good work ! Hopefully your backport PR will be tested by the continuous integration and merged soon!

If these instruction are inaccurate, feel free to suggest an improvement.

timhoffm pushed a commit to timhoffm/matplotlib that referenced this pull request Feb 1, 2020
@timhoffm timhoffm deleted the doc-overview branch February 1, 2020 13:01
tacaswell added a commit that referenced this pull request Feb 1, 2020
…v3.2.x

Backport PR #16226 on branch v3.2.x: Reorganize intro section on main page
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.

Prose error on website (first paragraph)
5 participants