Re: GSoD - Technical Writter

On Sat, May 18, 2019 at 05:13:30PM +0200, Ralf Gommers wrote:
> Hey Gael, I think you're mostly right that it's about theming, but not
> completely. Alabaster isn't really the kind of theme that helps. It's still for
> docs. For a modern website, Sphinx is just not a great tool. I'd love something
> like https://jupyter.org/ or https://julialang.org/, and then a Sphinx site
> under it for user and reference guides.

Sure, for the few landing pages (or for a blog), Sphinx isn't great. But
landing and summary pages can be done in a separate jinja template. By a
vast majority, the pages on a site like like of scipy are documentation
pages.

> I don't think Sphinx is the right tool for the job of building a modern
> top-level site.  

It does lack some nice features of a CMS, and the templating is clunky.

>     > Yes, there's https://scipy-lectures.org/ for example. Guiding
>     > users effectively to all existing resources will be a major step
>     > forward.

>     Glad to see some synergy here!


> Perhaps there should be even more synergy. Scipy-lectures and http://
> scipy.github.io/devdocs/tutorial/index.html partly overlap in content and
> scope, separating them better could help users and get us more good-quality
> material with less effort. I just don't know what the split should be. Any
> thoughts?

In a sense, there is bound to be some redundancy. Scipy must have a
getting started tutorial, because it is easier to maintain, link, and
update within scipy. But scipy-lectures brings the benefit of being able
to develop jointly multiple chapters that discuss various packages and
try to be didactic across chapters (which is does in a quite imperfect
way, I must say).

So I believe that both are needed. What should be important is to mix the
community of developers (aka doc writer), to benefit from the various
efforts. That said, I must say that I personally struggle to find time to
work on scipy-lectures. When I do, it's because I am teaching a course
and badly need an improvement. I have no brilliant idea to solve this. On
the positive side, scipy-lectures keeps getting nice improvements from
community members.

Cheers,

Gaël