I was thinking more about Aaron's mention of measuring the documentation use and started wondering how to get more and better insight into what is good and bad about our documentation. One issue that this conversation suffers from is that Aaron probably knows more about SymPy that almost anyone. Ondrej created it in 2006 and I've had 10 years experience with it too. I think it would be much more valuable to hear from new developers, non-developer users, and people that don't even know about SymPy. The old guns certainly have informed and useful insight to give but we simply don't use SymPy in the same way that these others do. They will likely give us insight that we really need to make the documentation useful and accessible.
With that in mind, a survey could be designed and sent out to our GSoC students form the last few years and we could post it to twitter and mailing lists (ours and others) to get some of the SymPy user base. For non-sympy users, I can imagine that it would be extremely useful to watch someone new to SymPy try to use the documentation (like we might see in a live tutorial). You could give someone a little task like "find the solution to these linear equations" and see what they do. Or just ask them to take a look at the documentation website and give some feedback. You could also ask people to compare our documentation to another similar software package. Maybe you could ask someone to write a docstring for a function or class after explaining what it does verbally and see how they'd write it and ask them why they wrote it in that way. Lot's of ideas here, but they take concerted time. Doing things like this could give us some nice data to support or not support various solutions. Jason moorepants.info +01 530-601-9791 On Tue, Aug 13, 2019 at 10:23 AM Jason Moore <moorepa...@gmail.com> wrote: > > I like this approach a lot. > > I agree. It is a nice idea. > > Jason > moorepants.info > +01 530-601-9791 > > > On Tue, Aug 13, 2019 at 10:22 AM Ondřej Čertík <ond...@certik.us> wrote: > >> >> >> On Tue, Aug 13, 2019, at 10:49 AM, Jason Moore wrote: >> > > I don't know that for sure, so maybe there is some way we could >> measure that. >> > >> > This is something Lauren could do, a proper survey to solicit feedback >> > on docstrings/documentation from users would really help. Right now we >> > are just getting info from a few vocal speakers. >> > >> > > Maybe our docstring standard should simply state that we haven't yet >> reached a consensus about this as a community, >> > >> > If conversations about style of code/documentation of the past are any >> > indication I don't think consensus will ever be reached (at least not >> > in the way our large group arrives at consensus). I personally don't >> > think we need consensus. I'm fine with letting Lauren take in the info >> > she gets and produce a what she thinks is best. Projects like black >> > <https://black.readthedocs.io/> arose because in some sense it doesn't >> > matter what the details of the standard are, but simply that there is >> > one. For example, if we have a LaTeX heavy docstring with consistency >> > across all docstrings, I think that is better than having lack of >> > consistency and different styles in each module. >> >> Yes, but I think it's a good occasion now to discuss and figure out a >> good solution. I am willing to write code for this, I think this is very >> important. If we can't figure this out in the next few weeks, then I agree, >> we will probably stick with LaTeX. >> >> I like Aaron's suggestion: >> >> .. sympy:: >> Eq(uppergamma(s, x), Integral(t**(s - 1)*exp(-t), (t, x, oo))) >> >> And to fix the := issue, why not to add this semantics to SymPy, as >> follows: >> >> .. sympy:: >> Def(uppergamma(s, x), Integral(t**(s - 1)*exp(-t), (t, x, oo))) >> >> And SymPy will have the capability to convert the Def to Eq if requested, >> or anything else we deem appropriate (such as conversion to and from >> Fungrim). >> >> Now take this example from our docs: >> >> .. math:: >> \Gamma(x) := \int^{\infty}_{0} t^{x-1} e^{-t} \mathrm{d}t. >> >> And the corresponding new way: >> >> .. sympy:: >> Def(Gamma(x), Integral(t**(x-1)*exp(-t), (t, 0, oo))) >> >> which is even 5 characters shorter. And our Sphinx extension can still >> convert it to the original LaTeX, it knows all the information. >> >> I like this approach a lot. >> >> Ondrej >> >> -- >> 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/49303907-5a06-4e3a-a1f3-17ac074f5475%40www.fastmail.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/CAP7f1AjLRbo-NfbOrdnJUPfA8jctNi1f%3DV5irdMUvond6exnxQ%40mail.gmail.com.
