[SciPy-User] GSoD - Technical Writter

[Ralf Gommers]

On Fri, May 17, 2019 at 6:57 PM Dashamir Hoxha <dashohoxha at gmail.com> wrote:

> On Fri, May 17, 2019 at 2:54 PM Ralf Gommers <ralf.gommers at gmail.com>
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-user/attachments/20190518/6b0d0d6c/attachment.html>