Hi Luca, On 2017-10-16, Luca De Feo <de...@lix.polytechnique.fr> wrote: > On Mon, Oct 16, 2017 at 7:35 PM, 'Martin R. Albrecht' via sage-devel ><sage-devel@googlegroups.com> wrote: >> Hi there, >> >> this is already documented: >> >> “ Return the normal form of self w.r.t. "I", i.e. return the >> remainder of this polynomial with respect to the polynomials in >> "I". If the polynomial set/list "I" is not a (strong) Groebner >> basis the result is not canonical. >> ” > > Can you tell from this documentation what the function will compute > prior to running it? I can't.
When reading `normal form` and `Groebner basis` in the same sentence, the meaning should be clear to anybody who took a course in commutative algebra. So, the question is: Whom should documentation be addressed to? I do *not* think that documentation should always be addressed to non-experts. Here, we talk about methods of polynomials respectively polynomial ideals. Thus, a user having a closer look into it is, to some extent, assumed to know about commutative algebra. In addition, if the documentation mentions a technical notion such as `Groebner basis`, and it doesn't ring a bell to the user, then of course the user should either conclude right away that the method might not be what (s)he was looking for, or should look up the technical notion before drawing that conclusion. Just for comparison: In the method galois_conjugates of number field elements, it says right in the beginning Return all Gal(Qbar/Q)-conjugates of this number field element in the field K. No explanation what that actually means. Again "of course", if the user doesn't know what Gal(Qbar/Q) means and just knows from calculus that there is a conjugation in CC (which is why (s)he stumbled upon the method), (s)he should certainly not expect to understand every detail of the documentation. And likewise for polynomial reduction. Best regards, Simon -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
