You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The landing page for the matplotlib documentation link https://matplotlib.org/devdocs/contents.html is simply a table of contents, which can be hard to navigate for someone unfamiliar with matplotlib.
Suggested Improvement
Rework this page so there's some roadmapping/guidance on what the different parts of the documentation are. For example, the Pandas docs (https://pandas.pydata.org/docs/):
Or the numpy docs which require less HTML/CSS/work but still has more guidance (https://numpy.org/doc/stable/):
actually I wanted to have more insights on rendering the docs why do we need to copy from other I believe it needs to be enhanced but we can create a custom layout. @story645 and sure I will put my doubts on gitter for a through deliberation. but how to join this dev call. My last PR hasn't been merged yet and I am also not a member of this repository.
The dev call is open to the public to discuss any PR, we put the link in the gitter day of. We don't need to copy from pandas or numpy, they're just ideas of similar projects and familiar UX tends to be welcome.
I think it'd be useful for you to open a PR or issue or post on discourse w/ some of your ideas that we can then discuss.
@story645 I had a thought regarding a format of the landing page. Instead to redirecting the user to a new page we create create a page having a column in the left with all the topics and subtopics mention in the left somewhat like pycaret documentation page has https://pycaret.readthedocs.io/en/latest/
(see here) but what I would like to add here in the left column like adding a second level of column to it containing the subtopics of the topic like here taking the case of pycaret if I were doing it for them I would add each function involved in each topic for eg classification under that topic in the second level of left column.
to add here in the left column like adding a second level of column to it containing the subtopics of the topic like here taking the case of pycaret if I were doing it for them I would add each function involved in each topic for eg classification under that topic in the second level of left column.
I'm sorry, I'm having trouble following how this is a solution to the docs issue (rather than a homepage redesign like the caret page). Can you please at least sketch up a wireframe of your proposal?
Thanks, much clearer! I'm not sure though how it addresses the roadmapping problem since if I'm reading it right, folks would have to hover each section to learn what it's about?
That is I think what I would want from that page. But I don't think it's a good pattern for a top level tab to link to the lowest heading in a page. So maybe that's a sign that that explanation of usage patterns really belongs somewhere else? (At least under the proposed re-organization)
I would be against duplicating Contents and the home page with almost the same information.
I am somewhat happy with the recent changes to the home page, spearheaded by @timhoffm and @story645, though there is always room for improvement.
What @ianhi is suggesting (I believe) is a rethink of the top-level menu bar that currently says "Installation" "Documentation" "Examples" "Tutorials" "Contributing", in particular to get rid of "Documentation" and replace with "API".
I think the old organization came from the idea that the webpage was somehow separate from the "docs" and that the docs needed a narrative table of contents. Its 2021, and I'd say the webpage is the docs, and given the improvements to the home page, I really think the idea that the docs need a separate landing page should be rethought, which I think is what @story645 is suggesting.
I would be against duplicating Contents and the home page with almost the same information.
one thing to note is that both of your links are essentially the top level of the docs.
the webpage is the docs,
The numpy & pandas home pages have changed to be more holistic https://numpy.org/, https://pandas.pydata.org/, which is in line with the level of detail on the matplotlib homepage. The screenshots I posted are for the pages you get by clicking on the documentation tab of each homepage. I think a secondary confusion here is that their docs sites are styled differently from their homepages (and may even be different sites ). while in the current matplotlib site, these are sort of clobbered together. I'm not opposed to adding/changing tabs
Installation - Tutorials - Examples - API Reference - Contributing
but I don't think that's in conflict with reworking the docs landing page to provide some guidance on which part of the docs folks should go to. So I think the last wireframe @rajpratyush is in the right direction since it is strictly focused on the docs page. Though there is also the question of what shoud be pulled out of that table of contents - like third party package stuff is really ecosystem anyway.
IMHO the landing page is only a secondary problem. The major issue is that we in parts don't have a reasonable structure on the site. And that deficit makes it hard for the landing page to have meaningful structure and links. Sometimes, we don't have the proper pages to link to, and sometimes we have to include lines to make pages accessible, but the links don't really fit the desired scope.
So before we get to redesign the landing page, we need to reorganize the site. The landing page with then make itself evident from the structure.
Todo: Define categories, purpose and intendend audience for the existing pages and reorganize them.
@timhoffm@story645 did you checked my second wireframe. I think it will solve our problem and it will be interactive as well please go though it once and do tell me your opinions
@rajpratyush I like the overall idea. Probably needs still some fine-tuning. My larger point is that we can only do this after restructuring the site because we currently don't always have proper pages we can to link to from the landing page.
We don't have a list because we don't fully know the answer to that question - someone has to go through the whole site and figure out what's there and how it's currently linked together (a full UX inventory) which I think is why @tacaswell pulled the good first issue label off this PR.
well @story645 that would definitely take more than one brain for sure. if you are willing to I have one friend with whom I can collaborate and work together on resolving this issue.
Hi @rajpratyush, we had a discussion on this and think that might be a bit too much as a new user contribution. But, if you and your friend are interested in doing a big documentation project, #18277 might be a good fit. The tasks involved are:
create a blank sphinx gallery page
fill it w/ minimal examples of each type of chart - the type of data the chart expects & the plotting call, no parameter tweaking
Activity
rajpratyush commentedon Feb 1, 2021
@story645 I would like to work on this. Can I?
story645 commentedon Feb 1, 2021
Go for it!
rajpratyush commentedon Feb 1, 2021
well before that can I have a short and brief google meet or zoom call so as to better discuss the layout of matplotlib's docs page?
story645 commentedon Feb 1, 2021
We have our dev call Thursday, but you can drop into our gitter to ask questions https://gitter.im/matplotlib/matplotlib
rajpratyush commentedon Feb 1, 2021
actually I wanted to have more insights on rendering the docs why do we need to copy from other I believe it needs to be enhanced but we can create a custom layout. @story645 and sure I will put my doubts on gitter for a through deliberation. but how to join this dev call. My last PR hasn't been merged yet and I am also not a member of this repository.
story645 commentedon Feb 1, 2021
The dev call is open to the public to discuss any PR, we put the link in the gitter day of. We don't need to copy from pandas or numpy, they're just ideas of similar projects and familiar UX tends to be welcome.
I think it'd be useful for you to open a PR or issue or post on discourse w/ some of your ideas that we can then discuss.
rajpratyush commentedon Feb 4, 2021
@story645 I had a thought regarding a format of the landing page. Instead to redirecting the user to a new page we create create a page having a column in the left with all the topics and subtopics mention in the left somewhat like pycaret documentation page has
https://pycaret.readthedocs.io/en/latest/
(see here) but what I would like to add here in the left column like adding a second level of column to it containing the subtopics of the topic like here taking the case of pycaret if I were doing it for them I would add each function involved in each topic for eg classification under that topic in the second level of left column.
@timhoffm what are your thoughts on this
story645 commentedon Feb 4, 2021
I'm sorry, I'm having trouble following how this is a solution to the docs issue (rather than a homepage redesign like the caret page). Can you please at least sketch up a wireframe of your proposal?
rajpratyush commentedon Feb 4, 2021
yes @story645 surely can I put up rough pen sketch so that you can have an insight or should I explain it verbally on the dev call?
story645 commentedon Feb 4, 2021
I think pen sketch would be very helpful and make it easier to follow a verbal explaination.
rajpratyush commentedon Feb 4, 2021
yess but don't count on my sketching skills they are very bad but I have explained all functionalities throughly. @story645
rajpratyush commentedon Feb 4, 2021
few more provisions like viewing the source and view on github are not added here

story645 commentedon Feb 4, 2021
Thanks, much clearer! I'm not sure though how it addresses the roadmapping problem since if I'm reading it right, folks would have to hover each section to learn what it's about?
13 remaining items
jklymak commentedon Feb 5, 2021
@ianhi I almost always just want to go to modules: https://matplotlib.org/devdocs/api/index.html#modules All the verbiage before hand just makes for an extra click.
ianhi commentedon Feb 5, 2021
That is I think what I would want from that page. But I don't think it's a good pattern for a top level tab to link to the lowest heading in a page. So maybe that's a sign that that explanation of usage patterns really belongs somewhere else? (At least under the proposed re-organization)
The equivalent numpy page (https://numpy.org/doc/stable/reference/index.html) has a brief sentence on top and then jumps right in to what you are looking for.
rajpratyush commentedon Feb 5, 2021
@story645 what do you think will this wireframe solve the road mapping problem in the landing page

jklymak commentedon Feb 5, 2021
I get the feeling we are talking about two different pages..
Our landing page is http://matplotlib.org/stable/ which is not wildly different than the above sketches.
@story645 is discussing the contents page https://matplotlib.org/stable/contents.html, which you get to, confusingly, but pressing either the Contents in the breadcrumb, or Documentation in the header.
I would be against duplicating Contents and the home page with almost the same information.
I am somewhat happy with the recent changes to the home page, spearheaded by @timhoffm and @story645, though there is always room for improvement.
What @ianhi is suggesting (I believe) is a rethink of the top-level menu bar that currently says "Installation" "Documentation" "Examples" "Tutorials" "Contributing", in particular to get rid of "Documentation" and replace with "API".
I think the old organization came from the idea that the webpage was somehow separate from the "docs" and that the docs needed a narrative table of contents. Its 2021, and I'd say the webpage is the docs, and given the improvements to the home page, I really think the idea that the docs need a separate landing page should be rethought, which I think is what @story645 is suggesting.
story645 commentedon Feb 5, 2021
The numpy & pandas home pages have changed to be more holistic https://numpy.org/, https://pandas.pydata.org/, which is in line with the level of detail on the matplotlib homepage. The screenshots I posted are for the pages you get by clicking on the documentation tab of each homepage. I think a secondary confusion here is that their docs sites are styled differently from their homepages (and may even be different sites ). while in the current matplotlib site, these are sort of clobbered together. I'm not opposed to adding/changing tabs
but I don't think that's in conflict with reworking the docs landing page to provide some guidance on which part of the docs folks should go to. So I think the last wireframe @rajpratyush is in the right direction since it is strictly focused on the docs page. Though there is also the question of what shoud be pulled out of that table of contents - like third party package stuff is really ecosystem anyway.
jklymak commentedon Feb 5, 2021
I would prefer not to have to click 3 times to finally get to the API
timhoffm commentedon Feb 6, 2021
IMHO the landing page is only a secondary problem. The major issue is that we in parts don't have a reasonable structure on the site. And that deficit makes it hard for the landing page to have meaningful structure and links. Sometimes, we don't have the proper pages to link to, and sometimes we have to include lines to make pages accessible, but the links don't really fit the desired scope.
So before we get to redesign the landing page, we need to reorganize the site. The landing page with then make itself evident from the structure.
Todo: Define categories, purpose and intendend audience for the existing pages and reorganize them.
rajpratyush commentedon Feb 6, 2021
@timhoffm @story645 did you checked my second wireframe. I think it will solve our problem and it will be interactive as well please go though it once and do tell me your opinions
timhoffm commentedon Feb 6, 2021
@rajpratyush I like the overall idea. Probably needs still some fine-tuning. My larger point is that we can only do this after restructuring the site because we currently don't always have proper pages we can to link to from the landing page.
rajpratyush commentedon Feb 6, 2021
@timhoffm yes I agree the wireframe needs some fine tuning. Can you tell me all the pages which needs restructuring
story645 commentedon Feb 7, 2021
We don't have a list because we don't fully know the answer to that question - someone has to go through the whole site and figure out what's there and how it's currently linked together (a full UX inventory) which I think is why @tacaswell pulled the good first issue label off this PR.
rajpratyush commentedon Feb 9, 2021
well @story645 that would definitely take more than one brain for sure. if you are willing to I have one friend with whom I can collaborate and work together on resolving this issue.
story645 commentedon Feb 21, 2021
Hi @rajpratyush, we had a discussion on this and think that might be a bit too much as a new user contribution. But, if you and your friend are interested in doing a big documentation project, #18277 might be a good fit. The tasks involved are:
story645 commentedon Jul 25, 2021
closing in favor of #20737