Google Season of Docs – org application deadline April 2

[Matthias Koeppe]

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?

[David Roe]

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 (compared to Mathematica's), some suggestions here 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

--
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.

[John Cremona]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/CAChs6_mEgnbGQgJQHuT9rXLJZMtitYe1CxkUG9Fy0iFGqONRHg%40mail.gmail.com.

[Dima Pasechnik]

Not sure whether switching Sage to standard Sphinx/Python docbuilding tools falls within the remit  of the Season of Docs, but it's surely a worthwhile project - in particular if we can get funds for it.

To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/CAChs6_mEgnbGQgJQHuT9rXLJZMtitYe1CxkUG9Fy0iFGqONRHg%40mail.gmail.com.

[Matthias Koeppe]

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.

[David Roe]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/b0f16004-6364-4991-ae6f-7361e3b40ed7n%40googlegroups.com.

[John H Palmieri]

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.

[Dima Pasechnik]

On 11 March 2024 05:39:36 GMT, John H Palmieri <jhpalm...@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.

>>>>> 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/>

>>>>>> <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>
>>> .
>>>
>>
>

[Matthias Koeppe]

On Saturday, March 9, 2024 at 2:13:06 PM UTC-8 Matthias Koeppe 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

Thanks all for sharing your thoughts.

1) Yes, this program is for actual technical writing. We should not try to use it for what amounts to programming tasks. I don't think we would be successful in getting a project funded that misses this key point!

2) Yes, Dima is right that we would be in charge of finding the person that would be hired for this project. 

3) Hence, a perhaps more important question than who would be applying/supervising the project is: How would we recruit the "technical writer" to be hired in the project? 

4) I think it's important to point out that the "technical writer" does not need to hold a certification from the Guild of Technical Writing or anything like that. We could simply be looking for a mathematician who wishes to dedicate 6–7 months (part-time) on writing for our project. This could even be based on existing materials such as their lecture notes or abandoned book manuscripts.

5) Here's a sketch of a possible GSoD project that I would find very valuable for Sage: Improved integration with upstream/peer projects through writing 

- Technical preparation: Intersphinx for cvxopt, cvxpy, cypari2, cysignals, flint, fpylll, gmpy2, ipywidgets, matplotlib, mpmath, networkx, numpy, rpy2, scipy, sympy (https://github.com/sagemath/sage/pull/37575, needs review)

- Technical preparation: HTML documentation: Show preparsed doctests using inline tabs (https://github.com/sagemath/sage/pull/37083, needs review)

- In our SPKG.rst files, explain how SageMath makes use of the package (https://github.com/sagemath/sage/issues/37586)

- Add badges for GitHub stars of upstream projects (https://github.com/sagemath/sage/issues/37585)

- Documentation and scripts to direct bug reports to upstream or downstream projects (https://github.com/sagemath/sage/issues/37382)

- Broaden the developer's guide to more than just sagelib development: Guide people to the best place where they can make their contributions (https://github.com/sagemath/sage/issues/34526)

Matthias

[Kwankyu Lee]

... 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 agree. 

- It is very hard to find features and learn how to use them for a subject that I am not already familiar with (and also hard with a subject I am familiar with).

- Except the reference manual, all docs are more or less outdated, and no one is updating them.

I think the reference manual and the thematic tutorials should be combined. Each chapter of the reference manual of a subject or theme should have an introductory tutorial that explains major features Sage provides in the subject and how to use them. The chapter should be updated whenever a major feature is added to the subject.

I don't think we can find a "technical writer" to do the work outside of the sage community. Subject experts or major contributors to the subject would be the best technical writers to do the work. The fund may be used to support them to devote their time for the work.