David and Oscar, Glad there is agreement on the need for improved documentation! And that there's a Google Summer of Documentation to go along with the one of Code.
>There should be a guide somewhere that explains how to "solve equations". Definitely--web searches for things such as "SymPy solve inequalities" <https://www.google.com/search?q=sympy+solve+inequalities> return the Inequality Solvers <https://docs.sympy.org/latest/modules/solvers/inequalities.html> page, and there's nothing telling the visitor that they should probably be using a high-level solver such as solve() or solveset(). There also needs to be a page on how to programmatically parse results of e.g. solve()--there's nothing on the site that I could find. For example, to answer my StackOveflow question about parsing results <https://stackoverflow.com/questions/67153048/reliable-way-to-extract-values-from-parse-sympy-result>, smichr put together three concepts that I could not glean from the documentation, certainly not all in one place: 1. Solved inequalities can be parsed using .atoms() 2. .atoms() can be filtered using Relational 3. .canonical puts the atoms in order so the symbol is on the left I'd be happy to communicate with Joannah Nanjekye and Aaron Meurer about what documentation is needed, how I can help with existing efforts, etc. Because I'm new here, could you give me their contact information? Thanks, Jeremy On Sunday, November 28, 2021 at 3:37:02 PM UTC-5 Oscar wrote: > On Sun, 28 Nov 2021 at 11:09, Jeremy Monat <jem...@gmail.com> wrote: > > > > Hello, I'm Jeremy Monat. My primary interest in helping with SymPy > development is making it easier for new users to use SymPy by improving the > documentation. It is plenty powerful for the application I needed; learning > how to use SymPy was the challenge for me. > > Hello and welcome Jeremy. Contributions to improving the documentation > are absolutely welcome. There are a few things already happening in > relation to this. > > We've just had a GSOD (Google Summer of Docs) project working on > reorganising the documentation from a high-level. This was work by > Joannah Nanjekye looking at different aspects of how to organise > things. The most immediately noticeable change is the new front page > which you can see in the dev docs for the next release: > https://docs.sympy.org/latest/index.html > https://docs.sympy.org/dev/index.html > > There is plenty more to do in terms of organisation. I'd like to break > down the long API doc pages into smaller more organised pages more > like this: > https://numpy.org/doc/stable/reference/routines.fft.html > There was a PR to do that somewhere but it seems to have stalled. > > Another thing happening right now is that Aaron Meurer is being funded > by CZI to spend time writing new docs with a particular focus on > guides for general usage rather than basic API docs. I bet Aaron would > be grateful or any insights you have on what is really needed. > > Absolutely more is needed in improving the docs though. A good example > is that you said your interest area was solvers. There should be a > guide somewhere that explains how to "solve equations". There are so > many different options for doing this in SymPy and I don't think many > users understand what the pros and cons are or when each is > applicable. Instead of a good guide explaining these we have things > like this: > > https://docs.sympy.org/latest/modules/solvers/solveset.html#what-will-you-do-with-the-old-solve > That page implies that solveset will replace solve and that solve > should not be used any more (not at all true!). That kind of thing > leads to a lot of confusion for people learning to use SymPy because > it makes them think that they should use solveset instead of solve but > solveset does not even begin to replace solve because it doesn't > handle multivariate equations. > > -- > 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 sympy+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/11e75753-91be-4d3e-b18a-d744784b0badn%40googlegroups.com.
