Waldek,
Thank you for that explanation I, at least, found it really helpful,
especially the Mathieu group example.
> However, it is not really task of _reference_ documentation to
> provide education to such users. First, much of needed
> background knowledge can be found in existing mathematical
> texts. Second, beginning users need tutorials and tutorials
> are written in quite different way than reference documentation.
True, but I think the reference documentation needs to be more than the
'++' comments and the function signature.
In thinking about these things I try to put myself in the position of
someone who may be unfamiliar with everything in the code library. They
are looking for existing functions that may help them, there is a lot of
library code to scan through.
If I was scanning through this very quickly I would probably have
assumed that the free group was a presentation without relations and
this function was adding the relations (that is the free group was the
generators and not the relations). Its obviously not that when you look
at the code but should a new user have to trace though the code for
every function they are considering using?
I think this information needs to be part of the reference documentation
(Its explaining what the code does not the maths) and I think it needs
to be somewhere where it can be automatically picked up by Ralfs
program: https://fricas.github.io/api/index.html and other programs like
this.
Martin
--
You received this message because you are subscribed to the Google Groups "FriCAS -
computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.
