On Thursday, June 15, 2023 at 12:23:55 AM UTC+9 Matthias Koeppe wrote: On Wednesday, June 14, 2023 at 8:01:29 AM UTC-7 Tobias Diez wrote:
On Wednesday, 14 June 2023 at 05:37:15 UTC+8 Matthias Koeppe wrote: - Some # optional annotations reduce the barrier for contributors, by clearly signaling to developers "it's OK and definitely not your fault if you don't understand this doctest". [...] As a (new) user, reading "# optional - sage.symbolic" makes me more think "wtf. what is this? how do I install this sage.symbolic thing so that I can run use this example?!" than "oh, yes, this test depends on another part of sage, that I have not yet encountered, so I don't need to try to understand this example". This is a documentation / user education issue, which is addressed by writing documentation and educating the educators first. I don't think the answer should be "read this long, technical document' to understand." Even if it is a short and easy to understand, how would a random casual user who just heard about Sage know to even look for it? It seems like you want to make the people who are doing Sage outreach do more selling and explaining to people (who probably won't even remember such a minor point when they first start playing around with things). Some of it can be fixed by changing the nomenclature "optional" to something else as that suggests something a user should *add* to the installation. Perhaps this is the core question (for me): What do you expect most/casual users to download and install? Let me expand on this more. Right now, us developers distinguish between sage-the-library and sage-the-distribution internally, but when we go to "sell" our product, there is but one Sage (to rule them all). There is no outward facing sign that a user needs to care about the technical implementation details, but I feel they shouldn't. They can treat Sage as a black-box until they have a reason not to (e.g., trying to fix a bug or prove some code is correct). I think we need to keep this end-user experience in the forefront of our minds. Best, Travis -- 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 view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/8edaf240-b378-437d-9a61-d9f37a7cd9a0n%40googlegroups.com.
