Aaron, Thanks. Great--the new documentation homepage <https://docs.sympy.org/dev/index.html> is much clearer with its division into 1) Tutorials <https://docs.sympy.org/dev/tutorial/index.html#tutorial>, 2) How-to Guides <https://docs.sympy.org/dev/guides/index.html#guides>, 3) Explanation <https://docs.sympy.org/dev/explanation/index.html#explanation>, and 4) API Reference <https://docs.sympy.org/dev/reference/index.html#reference>. With the old documentation <https://docs.sympy.org/latest/index.html>, my mental model of the content categorization was just 1) tutorial and 2) technical documentation. That's why I thought anything along the lines of a guide belonged in the tutorial.
*Diataxis Framework Categorization* Having those four categories also helpfully highlights the lack of guides. Currently, the top-level guides are only Getting Started, Contributing to SymPy, Assumptions, and Symbolic and fuzzy booleans. Having a roadmap for which guides we'd like to add would be helpful so whoever is available and interested could start building a guide, e.g. - we've already identified solvers, parsing solved equations, and parsing expressions - it would be helpful to have a guide explaining what kinds of things you can do with SymPy (Calculus, Linear Algebra, etc.), as the wiki tutorial <https://github.com/sympy/sympy/wiki/Tutorial> nicely does It's good that the breadcrumbs at the top of each new page indicate which category the page is in, e.g. SymPy 1.10.dev documentation <https://docs.sympy.org/dev/index.html> » Explanation <https://docs.sympy.org/dev/explanation/index.html> » Gotchas and Pitfalls <https://docs.sympy.org/dev/explanation/gotchas.html#equals-signs> for https://docs.sympy.org/dev/explanation/gotchas.html#equals-signs. Displaying the category even more prominently might be helpful. *Tutorial "What's next"* Typically, when I want to use a new package, I do the tutorial, then (unless otherwise directed) figure I'm on my own, so I search for my topic of interest. (Perhaps the documentation site admins can provide quantitative data about navigation patterns of new users.) The new tutorial simply ends <https://docs.sympy.org/dev/tutorial/manipulation.html> without suggesting where learners might want to go next. So it'd be helpful to add a "What's next" page at the end of the tutorial pointing learners to the guides--that seems like the most likely section they'd want, to learn more about any particular topic they came to SymPy to use. *My next step* I'll identify a first issue and create it in the tracker. Jeremy On Tuesday, November 30, 2021 at 11:21:57 PM UTC-5 [email protected] wrote: > On Tue, Nov 30, 2021 at 9:00 PM Jeremy Monat <[email protected]> wrote: > > > > Oscar, thanks for the information about SymPy's capabilities and > options. > > > > Because many of the pages we're discussing are in the tutorial, I think > it would be useful to lay out the current and proposed tutorial structure > in a document. I created a page on the wiki Tutorial structure on > docs.sympy.org. I started by pasting in the current tutorial structure > (at the page and topic levels), and suggest we collaboratively develop a > proposed structure. > > > > If there is a better medium, or someone else (e.g. Aaron Meurer) already > has something in the works, please let me know. > > Let's use the issue tracker for this. I'm still trying to figure out > in general how I plan to organize my documentation ideas. > > There are a few things here. First, regarding the "tutorial", I think > we shouldn't be misled. Currently the pages that exist are in the > tutorial, but that doesn't mean all pages should go in the tutorial. > We have recently made a new organization for our documentation, which > can be viewed at https://docs.sympy.org/dev/index.html. This is based > on the Diataxis Framework https://diataxis.fr/. Sections should go in > the place that make the most sense. I expect a large part of what we > are talking about will not be tutorial, but either explanation of > how-to guides (the recorded talk on the Diataxis page gives the best > explanation of the differences between these). In particular, the > current "tutorial" is actually an "introductory tutorial". It should > not really be expanded much, unless the material really is relevant > for a very first time user of SymPy. > > For solvers, there is a lot of stuff that needs better documentation. > A big problem also is that the current API of the solvers is itself a > bit of a mess, which makes it harder to document the "best practices". > I think what we should do for solvers is to break it down into smaller > pieces, which can be documented separately. Just as an initial idea, I > think we could use a top-level tutorial on intro to solving (which > already partly exists in the existing tutorial) that just goes over > the very basics and does things like stress the differences between > symbolic and numeric solutions. Then we can have several how-to guides > on different types of problems that might come up relating to solving, > like solving inequalities, finding roots of polynomials, and > manipulating the output of solve() and solveset(). There is also this > existing documentation on solveset that goes over the high-level > design, https://docs.sympy.org/latest/modules/solvers/solveset.html, > which mostly fits in the "explanation" Diataxis category. > > Aaron Meurer > > > > > Jeremy > > On Tuesday, November 30, 2021 at 11:35:15 AM UTC-5 [email protected] > wrote: > >> > >> Thanks for responding, > >> > >> On 29/11/2021 18:51, Aaron Meurer wrote: > >> > Can you clarify what you mean by "3.4.6"? This is the sort of issue I > >> > plan on addressing as part of my CZI documentation project. > >> > > >> Yes, sorry I was referring to the section > >> > >> 3.4.6 Sqrt is not a Function > >> > >> in the PDF version of the 1.8 documentation (I guess the numbers > >> probably change from version to version - so I should have used 1.9. > >> > >> David > >> > > -- > > 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/f9bed2ab-789d-445f-bb03-d696fc8ab43fn%40googlegroups.com. > > > -- 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/e6a74d60-fb49-404f-8e88-c12ed3ee72d8n%40googlegroups.com.
