Blog post on SymPy Documentation

[asmeurer]

I still need some help here with cleaning up the formatting and the metadata. Feel free to push up changes directly to my branch.

I'd like to get this posted by the end of the month if possible so that I can reference it in our grant report to CZI.

Text styling

• The blog is written with plain language (where relevant).
• If there are headers, they use the proper header tags in order to do so (with only one level-one header).
• All links describe where they link to (for example, check the Quansight labs website).
• Any kind of styling that the author uses (for example, bold for emphasis) is consistent throughout the blog.

Non-text contents

• Blog post featured image is in PNG or JPEG format, not SVG.
• All content is represented as text (for example, images need alt text and videos need captions or descriptive transcripts).
• If there are emojis, there are not more than three in a row.
• Don't use flashing gifs or videos.
• If it were to be read as plain text, the blog still makes sense and no information is missing.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
labs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 31, 2023 6:57pm

[gabalafou]

This is really clear and easy to follow, great job!

Most of my suggestions are about changing which text you hyperlink because I think a lot nowadays about how links show up in assistive tech. I strive to make pages so that if you pull out all of the links in a list separate from the page, the links will still mostly make sense.

[gabalafou]

Such as? Should you list them here?

[gabalafou]

I'm wondering if instead of having this long form content live in the format of a list, if it would be more reader-friendly to give a shorthand version of the content in a short list and then follow into what you've written below, like so:

Suggested change

	three main takeaways of the survey were:
	1. The main SymPy documentation site (https://docs.sympy.org) is overwhelmingly
	three main takeaways of the survey were:
	1. SymPy's own documentation site is more popular than other resources such as StackOverflow.
	2. Organization and layout needed improvement.
	3. The community wanted new documentation areas.
	The main SymPy documentation site (https://docs.sympy.org) is overwhelmingly

Something like that

[gabalafou]

This may be just a personal preference thing. But I'm not sure about putting such long passages in a bulleted list.

[gabalafou]

I just pushed 3 commits. Please be sure to review them.

[gabalafou]

Happy to answer any questions about the changes I made

[gabalafou]

I just now pushed one more commit to update some places I missed when moving the screenshots around.

[rgommers]

This reads really well, thanks @asmeurer. And thanks for the detailed review @gabalafou. I only had two minor comments, so I'll just give this my 👍🏼 and let you two finish it off.

[rgommers]

minor formatting: should there be spaces around the -?

[rgommers]

It may be useful to say something like "We are aware of in-progress work to do exactly this in jupyterlite-sphinx" (this is what Albert demoed in the Labs meeting last week, and it's a deliverable on the Scientific Python grant).

[asmeurer]

I'm not really familiar with that effort, but I'd love to sync with @steppi about this.