There appear to be some broken references.

I think this rearrangement makes most sense to me. Color code: yellow: section stays as is orange: renamed/rescoped/merged see arrow for where it goes.

I'm almost tempted to instead put all three pages together under "Write documentation". Because we now have an imbalance in the top-level structure. Basically each topic is one page, but documentation is 3 (or with this PR 4) pages.

Each section is between 2-4 pages and docs is its own section:

But part of the issue is that "build docs" really belongs under development workflow but I dunno if anyone would find it there and the primary motivation for this PR was to make it easier to find the build docs because the current structure buries it. I agree w/ you that my structure doesn't quite work because there's meta "about the docs" documents that don't have a place anymore, and I agree w/ your suggestions about merging up into API and Examples/Tutorials sections (was gonna do that in a follow up) but here's an alternative that I think includes everything

Semi explicitly one of the things I'm shaking out here is that tutorials and user guide are ill-defined in terms of content guidelines, and an advantage of making content it's own page is that then it makes more sense to have rst and sphinx gallery as their own sections on a mechanics & conventions page-but the more I think on it the less I think they should be their own big sections cause they're mostly summaries/highlights from the sphinx and sphinx-gallery docs. And it gives space to grow out as we figure out what 'write the docs' content is specific to tutorials and/or userguide.

Also a lot of the file structure content overlaps with the readme/rst content, so I'd wanna refine the content in overview/file structure so anything specific to readme/rst gets pushed out.

Another maybe cleaner break along similar lines is:

• build
  • overview becomes a short preamble in build rather than a standalone section since the content overlaps with the readme info and where are things is in the contribution guide
  • build
• Sphinx and Extensions
  • rst
  • Sphinx - gallery
  • moving files
  • navbar
• Documentation (Content/Style Guide)
  • additional resources as tips section
  • conventions
  • API docs
  • examples
  • analytics

Hm, the more I think about this the more unclear I am on the right organization. Here are some random and somewhat inconsistent thoughts. Take then as brainstorming not as suggestions or requests.

• Wording: Documentation Guide feels like the overall heading.

• I don’t like „mechanics“. Maybe it’s just the word (something like Technical Aspects feels a bit more to the point but still not great), maybe it’s partly because it’s hard to separate that: Build is also „mechanical“. And see the next point

• I have the feeling that Sphinx gallery and writing examples should be close. They are both only relevant for the task of writing examples. Should we focus on different documentation tasks? OTOH there are many cross-cutting concerns like ReST, Build, etc.

• does the concept of the four kinds of documentation apply / give structuring insights? If so, are we clear what we do / need? I guess it’s mostly Reference Documentation?

• The additional resources links are not helpful as is. The framing

  This style guide is not a comprehensive standard. For a more thorough reference of how to contribute to documentation, see the links below. These resources contain common best practices for writing documentation.

  Suggests that we think it’s a good idea to follow at least parts of them as well. But these are large documents and it’s unclear which parts are relevant, so a user is quite lost with that info. It’s not actionable. I‘m wondering (1) do we need these links at all. It may be better to limit ourselves to the aspects that we explicitly define and leave everything else unspecified. (2) If we still want these links, rephrase that they are just a source of inspiration if somebody wants to dive deeper into the topic of documentation but it’s not needed to know these to contribute to our docs. In that sense they should be at the very end as further reading / additional resources, not at the beginning.

• is it worth starting small and moving some aspects which we already know we want together. E.g. move tagging to the existing examples. Move style guide/formatting/ReST to Writing ReST?

I have the feeling that Sphinx gallery and writing examples should be close. They are both only relevant for the task of writing examples.

Was editing my previous comment as you posted, but also sphinx-gallery content is relevant to examples, tutorials, and user guide and I strongly believe that the conflating of the three is heavily contributing to the organization and scoping issues of all three sections.

does the concept of the four kinds of documentation apply / give structuring insights

That's sorta where I was going with the edited proposal above:

• Build - how to guide akin to the other workflow docs
• Sphinx & Extensions - tutorial on using sphinx/sphinx-gallery/extensions for writing matplotlib docs
• Documentation guide - this is the opinionated explanation of how to write docs for Matplotlib

If we still want these links, rephrase that they are just a source of inspiration if somebody wants to dive deeper into the topic of documentation but it’s not needed to know these to contribute to our docs. In that sense they should be at the very end as further reading / additional resources, not at the beginning.

Yes, that's what I was thinking, but also having them as embedded drop-down kind of like we already do for the git resources
https://matplotlib.org/devdocs/devel/development_setup.html#id3

is it worth starting small and moving some aspects which we already know we want together. E.g. move tagging to the existing examples. Move style guide/formatting/ReST to Writing ReST?

That's sorta was what I was aiming for here by just pulling build out into it's own page and not doing a bigger restructur, but I can scale back and not rename anything else. I'm being stubborn about build b/c:

• Getting to it is a pain point for me
• It was specifically flagged in the sprints as a pain point
• We used to have a button specifically going to it

But also yes also maybe worth merging the definitely belong together things. I'm slightly iffy on if tagging should be moved into examples or hang off it b/c of the length/special purpose of the doc.