can I do this task

@pukarlamichhane
This is a pull request, which means that if you click on review changes you'll see what I've written for this task. You're welcome to add to it though.

Thanks for the review @timhoffm! One of the things I've been considering is pulling all the content guidelines into their own document. Not sure if it makes sense here or in a follow up, but for starters:

• this PR
• @esibinga 's gallery guidelines https://matplotlib.org/devdocs/devel/tag_guidelines.html#related-content
• your API guidelines: [Doc] Updated Hatches API page  #27370 (comment)

And also I know we've gotta have a discussion on all this b/c I don't think there's consensus on whether we should even have guidelines. I honestly feel like organizing the docs is a complete waste of time without content guidelines because guidelines are how we enforce organization, but also that it's even worse if we have content guidelines that we don't enforce.

However, I disagree that beginners should be able to random access the user guide and necessarily understand any given subsection without having understood some basic concepts first. Similarly, within a section, it should definitely begin straight forwardly and with strong motivation, but in further subsections we should be able to assume the reader has read the introductory material. If every section is written assuming nothing else has been read, then the user guide will be infinitely long and unbearable to read for people who have actually read some of the intro material.

What have I written here that implies that this is what I'm advocating for?

What have I written here that implies that this is what I'm advocating for?

These two phrases in particular could have more nuance:

The material is introduced in small, usually one change or task at a time, chunks to keep focus on the specific line of code enabling the given task.

... content should be written with the assumption that the reader does not yet know what Matplotlib calls a given visualization task nor how any task is accomplished in Matplotlib.

What knowledge we assume, or what we need to chunk varies by where we are in the docs.

What knowledge we assume, or what we need to chunk varies by where we are in the docs.

Can you elaborate on this?

Can you elaborate on this?

A lot of chunking or explanation for the initial parts of topics makes some sense. However as we get deeper into a topic, the need for explanation and chunking should drop away as we assume more knowledge. As a trivial example, we shouldn't have to explain what fig, axs = plt.subplots() means or does for every page, etc as we get deeper into the User Guide

However as we get deeper into a topic, the need for explanation and chunking should drop away as we assume more knowledge.

Yeah, I went back in and added a bit about scaffolding, b/c that's what scaffolding is.

As a trivial example, we shouldn't have to explain what fig, axs = plt.subplots() means or does for every page, etc as we get deeper into the User Guide

Yeah, agree...what gave you the impression I was proposing this?

I think this page may be a good summation of what I'm trying to get at https://cambridge-community.org.uk/professional-development/gswkey/index.html where in Matplotlib the key concept is the Artist like how in Numpy it's the array or in Pandas it's the dataframe or in SKlearn it's the Model object

Reworked and pulled out into standalone page. Also following changes:

• @efiring suggested I write a short sentence or two about the purpose of each section, so that's now at the top anchoring this doc. (Sidenote-found this suggestion really helpful in that I think all the docs together helps contextualize the individual page guidelines)
• Pulled in @timhoffm's API guidelines
• @esibinga's Example guidelines from the tagging guidelines
• plot type guidelines from the plot type gallery,
• added a new section for tutorials b/c one of my takeaways from all the discussions is it's really hard to define user guide independent of tutorials.
• updated the content guidelines to include differentiation

@story645 I have read the majority of this now (but not all details of the User guide section). Here's my feedback:

• The fundamental idea of explicitly writing down the purpose and how to write the different parts of our documentation is great. - And I believe basically all core devs will agree with this.
• I think, you're doing too much in this PR, which is why the PR is not moving forward well: 1. It's too much in volume - a reviewer needs quite some time to dig into this (this is also why I myself pushed looking into this forward again and again). 2. It's too much in complexity, in particular the "User guide" section is quite a construct, and by itself a possible source of longer debate.
• Apart from the review aspect: Can we make this more compact? The document feels quite long, and the longer it is the less people will read it. I propose as a general guiding question: With how little content and conceptual overhead can we reasonably cover the topic? - I'm particularly thinking of the "User guide" here, but also e.g. of the introduced term "modality" for the type of documentation.

To move forward, I propose to split this up and in a first step cut off after the summary (probably simplest to 1:1 copy that part to a new PR and start discussing there). The detailed descriptions of the individual sections can be handled later.

It's too much in complexity, in particular the "User guide" section is quite a construct, and by itself a possible source of longer debate.

So this PR started as just the user guide section, and what I found was I had to fold back the other information to contextualize the proposal for the user guide - basically I don't see how to propose a holistic approach to the docs w/o being holistic. Also don't see how to do a summary w/o the what is it summarizing.

ETA: also I have been consistently revising/updating the user guide proposal based on the feedback to this PR. The current proposal accommodates the existing documentation with relatively little reframing of a few documents (which would be necessary of any restructuring proposal) while also proposing a structure that communicates to the reader both audience and purpose.

But, I do hear you on the overwhelming so I propose spinning out each section into its own page and turning the summary page into the landing page for this section. And I'll see what I can slim down in each subpage. Also pulled the tutorials changes out to #27769

The detailed descriptions of the individual sections can be handled later.

Frankly, I don't see this happening if it doesn't go in w/ this PR and w/o details this guide isn't very actionable or useable to new contributors.

But, I do hear you on the overwhelming so I propose spinning out each section into its own page and turning the summary page into the landing page for this section.

Ok, this ended up being slightly absurd and likely to encourage scope creep on each individual page (demo) so instead wrote tldr summary for user guide and linked out to the detailed page. (and streamlined tutorial)