On 11 March 2024 05:39:36 GMT, John H Palmieri <jhpalmier...@gmail.com> wrote:
>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.
The program only provides funds. Organisations have to find people to employ as
"technical writers", but in a wide sense of the word, such a person can work on
Sphinx-related stuff.
If one proposes the task "documentation restructuring", Sphinx falls within
the remit of such a task, IMHO.
> 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/7A9DD1B5-DFB2-4BC6-AE28-801FEDB50593%40gmail.com.
