On Sun, 19 Jun 2022 at 09:01, Aaron Meurer <[email protected]> wrote: > > On Sat, Jun 18, 2022 at 3:49 PM Oscar Benjamin <[email protected]> > wrote: >> >> On Sat, 18 Jun 2022 at 13:45, Jeremy Monat <[email protected]> wrote: >> > >> > Aaron Meurer pointed out that we should move the solving main page before >> > the next release, so the page is in its final location when it gets >> > published to the "latest" (not dev) version of the documentation web site. >> > Given that, I'll make a simple pull request to reorganize the solving main >> > page from guides/solving.md to guides/solving/index.md. >> > >> > I included that reorganization in my draft pull request #23638 >> > Documentation guide: Solve an equation algebraically but the new sub-page >> > is still very much in development, so I'll split out the reorganization >> > into its own pull request. >> >> This reminds me that also I'm not really happy with the current >> organisation of the API docs: >> https://groups.google.com/g/sympy/c/L2zd54HDAxU >> >> If anyone wants to put some work into that then it would be good to >> get something in before the next release. > > > Isn't this something that's already a problem with 1.10? The only difference > in dev is the new theme, which makes organization issues more evident.
Yes, it's already a problem in 1.10. Ideally we would make it not be a problem in 1.11 though. Imagine being a new user or even an experienced user or contributor and you go to consult the docs for something starting from the main page: https://docs.sympy.org/dev/index.html >From there clicking through the different headings and then clicking through from those pages still nothing really makes sense. The guides section is mostly about contributing to SymPy apart from one very long page about the old assumptions. The tutorials page makes sense but the most important part (installing sympy) is for some reason in the guides section rather than the tutorial section. Probably there should be a big fat "installing" link right on the main page of the docs (perhaps similar for "contributing"). The "explanation" section seems completely random when you go and look at what's in there. Then there's the API reference which is organised in a way that doesn't really reflect any particular organisation that makes sense to anyone I think. It doesn't really break down into the kinds of things that users might want to do. Probably most of what a beginner would want to do is in "basics" but once you click through there the important stuff like "solvers" is really not very prominent. Clearly a lot of work is still needed on the organisation here but the basic question I want to ask about here is for the API reference: what is a good way to group the different aspects of SymPy into approximately 5 different categories that actually makes sense to users and also reflects what SymPy is actually useful for? -- Oscar -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAHVvXxRSj0KK%2BCeurbPiLtSB06qeUOJbRq%2Be%3Do3wFeu40j9_JA%40mail.gmail.com.
