Re: GSoD - Technical Writter

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: GSoD - Technical Writter

ralfgommers


On Fri, May 17, 2019 at 6:57 PM Dashamir Hoxha <[hidden email]> wrote:
On Fri, May 17, 2019 at 2:54 PM Ralf Gommers <[hidden email]> wrote:
Hi Dashamir,

Thank you for your email and interest in NumPy and SciPy. I'm excited about this program and opportunity to work with a technical writer. Please rest assured that we do not assume or expect you to be familiar with the project already. The scipy.stats idea we included in case someone would be familiar with it and wanted to work at the individual module level. Personally I think the most important and impactful thing though is to shape the structure of our documentation content. For that it's not necessarily an advantage to know numpy or scipy well - fresh eyes can be helpful. And in general, I'd say we have lots of people that can provide pieces of content; the ability to create the right framework/structure to effectively place and solicit that content is what we habe been missing. 

If you look at the NumPy and SciPy documentation, you will see that the reference guides (which are aimed at experienced users) are very large. The user guides (for beginning users) and the overall structuring could really benefit from a good technical writer.
 
Thanks for your encouraging message, Ralf.

Something that I can notice immediately is that the interface of the docs looks a bit outdated and maybe it can benefit from an update (or replacing it with another template), in order to make it a bit more responsive. It is true that when you program you usually work on a big screen, so a responsive web page may not be an absolute requirement, but still it may be nice to be able to read the docs from a tablet or smartphone.
Unfortunately I am not familiar yet with Sphinx, but I hope that it can be integrated with Jekyll or Hugo, and then one of their templates can be used.

You're right, the interface is a little outdated. Docs will have to stay in Sphinx (that's really the only choice for reST docs for a large Python package), however the top level websites (scipy.org, docs.scipy.org) could be moved to Jekyll or Hugo for a more modern look - this will actually be beneficial.


About the content of the User Guide etc. I don't see any obvious improvement that is needed (maybe because I have not read them yet). One thing that may help is making the code examples interactive, so that the readers can play with them and see how the results change. For example this may be useful: https://github.com/RunestoneInteractive/RunestoneComponents

I'd really like to stay with a static site, so that's unfortunately not the best option. It looks cool, but RunestoneServer requires a server - maintenance cost wise that's a showstopper.


The two changes that I have suggested above seem more like engineering work (for improving the documentation infrastructure), than documentation work. For making a content that can be easily grasped by the beginners, I think that it should be presented as a series of problems and their solutions. In other words don't show the users the features and their details, but ask them to solve a simple problem, and then show them how to solve it with NumPy/SciPy and its features. This would make it more attractive because people usually don't like to read manuals from beginning to the end. This is a job that can be done by the teachers for their students, having in mind the level of their students and what they actually want them to learn. I have noticed that there are already some lectures, or books, or tutorials like this. This is a creative work, with a specific target audience in mind, so I can't pretend that I can possibly do something useful about this in a short time (2-3 months). But of course the links to the existing resources can be made more visible and reachable from the main page of the website.

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

Cheers,
Ralf


_______________________________________________
SciPy-User mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/scipy-user
Reply | Threaded
Open this post in threaded view
|

Re: GSoD - Technical Writter

Gael Varoquaux
On Sat, May 18, 2019 at 04:40:50PM +0200, Ralf Gommers wrote:
> You're right, the interface is a little outdated. Docs will have to stay in
> Sphinx (that's really the only choice for reST docs for a large Python
> package), however the top level websites (scipy.org, docs.scipy.org) could be
> moved to Jekyll or Hugo for a more modern look - this will actually be
> beneficial.

Sphinx uses standard web tools as outputs (the jinja templating engine,
for instance). This problem, to me, is a theming problem: templating +
CSS. In scipy-lectures, I had done some work to build a theme that is
mobile friendly. More generally, I think that there would be value in
maintaining these themes in a way that can be shared across project.
Sphinx does have modern themes, such as
https://alabaster.readthedocs.io/en/latest/


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

Cheers,

Gaël
_______________________________________________
SciPy-User mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/scipy-user
Reply | Threaded
Open this post in threaded view
|

Re: GSoD - Technical Writter

ralfgommers


On Sat, May 18, 2019 at 4:52 PM Gael Varoquaux <[hidden email]> wrote:
On Sat, May 18, 2019 at 04:40:50PM +0200, Ralf Gommers wrote:
> You're right, the interface is a little outdated. Docs will have to stay in
> Sphinx (that's really the only choice for reST docs for a large Python
> package), however the top level websites (scipy.org, docs.scipy.org) could be
> moved to Jekyll or Hugo for a more modern look - this will actually be
> beneficial.

Sphinx uses standard web tools as outputs (the jinja templating engine,
for instance). This problem, to me, is a theming problem: templating +
CSS. In scipy-lectures, I had done some work to build a theme that is
mobile friendly. More generally, I think that there would be value in
maintaining these themes in a way that can be shared across project.
Sphinx does have modern themes, such as
https://alabaster.readthedocs.io/en/latest/

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. I don't think Sphinx is the right tool for the job of building a modern top-level site.
 



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

Cheers,
Ralf


_______________________________________________
SciPy-User mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/scipy-user
Reply | Threaded
Open this post in threaded view
|

Re: GSoD - Technical Writter

Gael Varoquaux
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
_______________________________________________
SciPy-User mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/scipy-user