Dima's suggestion is appealing, and somewhat along those lines, I like the idea changing Sage to use some standard documentation style (https://github.com/sagemath/sage/issues/31044). If the program provides a technical writer, though, those may not be suitable goals. A quick glance at least year's awards suggests a focus more on the writing and the content, not how it is technically presented or generated.
I don't know the whole history of our documentation, but at least some versions of it were written by people with no knowledge of how to write good software documentation — speaking only for myself and the parts that I've worked on. I'm guessing that a technical writer's eyes might spot things and see ways to improve them. We have lots of documentation, and I think that some of it is very good, probably explains lots of things clearly, but it may not always be written with the right audience in mind. I think we could use more organization surrounding the tutorial, the thematic tutorials, the PREP tutorials, constructions in Sage, a tour of Sage, and the FAQ; this could very well make the documentation more accessible and allow users to find documentation at the right level and with the right content for what they're trying to do. All of that is the documentation that we hope new users look at, and in my opinion that's where we should focus. On Sunday, March 10, 2024 at 8:00:03 PM UTC-7 David Roe wrote: > I think the main question is who is willing to take the lead on writing > and submitting applications (before April 2). I don't have enough time in > the next three weeks to do any writing, but I am willing to help brainstorm > what form the proposal(s) should take and help edit proposals if someone > else volunteers to write them. > David > > On Sun, Mar 10, 2024 at 6:18 PM Matthias Koeppe <matthia...@gmail.com> > wrote: > >> Yes, we could prepare several proposals for separate projects. >> One can see in the lists of past funded projects that some organizations >> have received funding for two simultaneous projects. >> >> On Sunday, March 10, 2024 at 8:38:13 AM UTC-7 John Cremona wrote: >> >>> Should there not be separate projects for documenting (1) building and >>> installing Sage; (2) using Sage (perhaps with some subject-specific >>> tutorials, some of which exist but might be worth updating) and (3) >>> documenting individual Sage functions and methods. >>> >>> These require different expertise, for example I recently found a badly >>> misleading docstring in the elliptic curves section, but only someone with >>> the right expertise would be able to rewrite it properly (yes, I will >>> create an issue for this soon!) >>> >>> John >>> >>> On Sun, 10 Mar 2024 at 15:03, David Roe <roed...@gmail.com> wrote: >>> >>>> I think this would be good for Sage. I think there are several >>>> decisions to be made: >>>> * What are our most pressing documentation needs? Personally, I think >>>> we have a gap between the reference manual (which is extensive but has no >>>> flow) and the thematic tutorials (which are written to tell a story but >>>> are >>>> just introductions). I also poked around online for criticisms of Sage's >>>> documentation and found complaints about not having separate pages for >>>> each function <https://news.ycombinator.com/item?id=23513654> >>>> (compared to Mathematica's), some suggestions here >>>> <https://www.reddit.com/r/math/comments/45q7j1/sagemath_open_source_is_now_ready_to_compete_with/> >>>> >>>> about focusing on aspects of Sage commonly used by beginners (like >>>> plotting). >>>> * Who will be involved in applying and supervising the project? This >>>> could be a group or a single person. I can help a bit, but I can't take >>>> the lead. >>>> David >>>> >>>> On Sat, Mar 9, 2024 at 5:13 PM Matthias Koeppe <matthia...@gmail.com> >>>> wrote: >>>> >>>>> SageMath could benefit from hiring a technical writer for a project to >>>>> improve the Sage documentation. Google Season of Docs is a program >>>>> that supports such projects. Some key facts: >>>>> - total project budget $5,000 - $15,000 USD (via OpenCollective) - >>>>> https://developers.google.com/season-of-docs/docs/org-payments >>>>> - starts April 10 (or May 22 the latest), ends November 22, 2024 - >>>>> https://developers.google.com/season-of-docs/docs/timeline >>>>> >>>>> Several of our peer projects (NumPy, Matplotlib, SymPy, R, Geomstats) >>>>> are among the orgs that appear to have made successful use of this >>>>> program >>>>> in the past few years, see >>>>> https://developers.google.com/season-of-docs/docs/2023/participants >>>>> etc. >>>>> >>>>> Thoughts? >>>>> >>>>> -- >>>>> 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+...@googlegroups.com. >>>>> To view this discussion on the web visit >>>>> https://groups.google.com/d/msgid/sage-devel/32bf06f2-6c35-40a9-855c-857c7af23799n%40googlegroups.com >>>>> >>>>> <https://groups.google.com/d/msgid/sage-devel/32bf06f2-6c35-40a9-855c-857c7af23799n%40googlegroups.com?utm_medium=email&utm_source=footer> >>>>> . >>>>> >>>> -- >>>> 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+...@googlegroups.com. >>>> >>> To view this discussion on the web visit >>>> https://groups.google.com/d/msgid/sage-devel/CAChs6_mEgnbGQgJQHuT9rXLJZMtitYe1CxkUG9Fy0iFGqONRHg%40mail.gmail.com >>>> >>>> <https://groups.google.com/d/msgid/sage-devel/CAChs6_mEgnbGQgJQHuT9rXLJZMtitYe1CxkUG9Fy0iFGqONRHg%40mail.gmail.com?utm_medium=email&utm_source=footer> >>>> . >>>> >>> -- >> 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+...@googlegroups.com. >> > To view this discussion on the web visit >> https://groups.google.com/d/msgid/sage-devel/b0f16004-6364-4991-ae6f-7361e3b40ed7n%40googlegroups.com >> >> <https://groups.google.com/d/msgid/sage-devel/b0f16004-6364-4991-ae6f-7361e3b40ed7n%40googlegroups.com?utm_medium=email&utm_source=footer> >> . >> > -- 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/d380af07-5305-433d-861c-83be4aed8536n%40googlegroups.com.
