I think the documentation stuff is a bit off topic here. We can improve documentation and have SymPEPs. In fact, if improving documentation requires a large concerted effort, that could itself be a SymPEP. However, I will note that on this front:
- We are participating in Google Season of Docs (GSoD, not to be confused with GSoC), which is a program that pays technical writers to work on open source documentation. The GSoD results will be announced in a couple of weeks, so watch this space. - I agree that we should have a concerted effort to improve documentation. A documentation sprint is one way. Getting funding to improve things is another. - We have a documentation style guide, which was developed as part of last year's GSoD. However, only a small subset of SymPy actually conforms to the guide https://docs.sympy.org/latest/documentation-style-guide.html. Aaron Meurer On Thu, Aug 6, 2020 at 1:48 PM Nikhil Maan <[email protected]> wrote: > > > > On Thursday, August 6, 2020 at 9:39:43 PM UTC+5:30 [email protected] wrote: >> >> A nice thing for a GSoD student to do would be to organize a documentation >> sprint. > > > This sounds like a great idea. > > I also like the idea of SymPy Enhancement Proposals. Another project that I > think might benefit SymPEPs is Naman Gera's work on adding control systems to > SymPy. It will be a great place for folks who would like to help > with/continue this work in the future to find the motivations and other > details about the decision choices and future plans. > > Looking at PEP-1 and seeing a large portion of the discussion in the thread > is regarding what kind of work should have a SymPEP and what they should > include, I think a good starting point for SymPEP-1 will be to describe what > are SymPEPs, why we are planning to add them, what kind of changes should > have a SymPEP, etc. Also, I like the sound of SymEP and SymPEP. +1 to calling > them SymPEP or SymEP instead of SEP. > > Regards, > Nikhil Maan > >> >> Jason >> moorepants.info >> +01 530-601-9791 >> >> >> On Thu, Aug 6, 2020 at 5:32 PM Matthew Brett <[email protected]> wrote: >>> >>> Hi, >>> >>> On Thu, Aug 6, 2020 at 4:10 PM David Bailey <[email protected]> wrote: >>> > >>> > On 06/08/2020 00:47, Nicolas Guarin wrote: >>> > >>> > I agree that this would be good for the project but maybe it would be a >>> > good idea to polish the documentation a bit. Some of the pages in the >>> > wiki are somewhat outdated and they are on the first results in a web >>> > search. >>> > >>> > Assuming you are talking about the user level documentation, I very much >>> > agree. >>> > >>> > If you look up even the simplest function - e.g. Sin[] - in Mathematica, >>> > you get a simple explanation, some examples showing that it can be used >>> > with real numbers, and that it 'knows' about special arguments such as >>> > Pi/3. >>> > >>> > It shows you the power series about zero and a plot of the function. It >>> > also shows some properties of the function such as Sin[x] = -Sin[-x] etc >>> > etc. >>> > >>> > It also shows that Sin can be applied to complex arguments, or even to >>> > matrices, and that it can be applied to a high precision floating point >>> > number to deliver a high precision result. >>> > >>> > That same level of detail is provided for every function - right up to >>> > complicated functions like MeijerG. Remember that for functions such as >>> > that, the documentation is even more important because there are >>> > different conventions as to the order,sign, etc of the arguments. >>> > >>> > This might appear like overkill, but it means that wherever you start you >>> > will realise a Mathemaica function is far more than just a numerical >>> > function. This is also true for SymPy, but the information is harder to >>> > find. It is also easy to cut/paste from the documentation into your own >>> > code. >>> > >>> > Of course, the documentation is massively redundant, but I imagine that >>> > the documentation for each function or operation would not be written >>> > from scratch, but pulled from some kind of database of information. >>> > >>> > Obviously the SymPy documentation can't jump to the Mathematica standard >>> > overnight, but maybe a student could put together some sort of framework >>> > from which such documentation of the standard maths functions could be >>> > generated, and start the process off - then others could contribute >>> > information that would fit into the same scheme. >>> > >>> > I think that such documentation would make SymPy very much more >>> > user-friendly. >>> >>> Just to say - that the Scipy Documentation Project took Numpy from >>> fairly woeful documentation, to very good documentation, in a few >>> months, and with a fairly small budget: >>> >>> http://conference.scipy.org/proceedings/SciPy2008/paper_5/ >>> https://ieeexplore.ieee.org/document/6879046 >>> >>> Cheers, >>> >>> Matthew >>> >>> -- >>> 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/CAH6Pt5q%3DN_Vb0Z_yM2w8nBKwFFJu8UPBO3_A0c1UeWhAKDBX%3Dg%40mail.gmail.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/b977b777-52de-43af-81c9-445662ffef9bn%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/CAKgW%3D6JkF1TDtukEcHJZdOPn9oG0z_BrbJ55dKNX8J9nfSSVMg%40mail.gmail.com.
