On Wed, Dec 1, 2021 at 9:12 PM Jeremy Monat <jemo...@gmail.com> wrote: > > Aaron, > > Thanks. Great--the new documentation homepage is much clearer with its > division into 1) Tutorials, 2) How-to Guides, 3) Explanation, and 4) API > Reference. With the old documentation, 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 nicely > does
That's why guides are the main focus of my project. As for a roadmap, my plan is to use a combination of issues, questions here on the mailing list and in other places like StackOverflow, and a user survey which is currently running (at https://forms.gle/EjkFEdnLXaYxjvfn6 for anyone who hasn't yet taken it) to get a better idea of our documentation needs. I haven't yet worked out how I want to keep track of this stuff. Most likely I will have a tracking issue, but I may also end up using something more dynamic to take notes for myself on what I see that needs documenting. > > 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 » Explanation » > Gotchas and Pitfalls 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 > 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. That's a good idea. Aaron Meurer > > 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 asme...@gmail.com wrote: >> >> On Tue, Nov 30, 2021 at 9:00 PM Jeremy Monat <jem...@gmail.com> 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 da...@dbailey.co.uk >> > 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 sympy+un...@googlegroups.com. >> > 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 sympy+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/sympy/e6a74d60-fb49-404f-8e88-c12ed3ee72d8n%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 sympy+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6%2BAAMjOqLSWPwCErmDFFQs89Ts3MomsCdhsyix66Hkx_A%40mail.gmail.com.
