Re: [Numpy-discussion] GSoD - Technical Writter

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

Re: [Numpy-discussion] GSoD - Technical Writter

Chris Barker - NOAA Federal

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

Sphinx is powerful, featurefull, and the standard doc system for Python. Let’s just stick with that.

But there are a LOT of themes available for Sphinx— I’m sure there are responsive ones  out there that could be used or adapted.


You might check out the bootstrap theme:


-CHB



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

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.

Best regards,
Dashamir
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

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

Re: [Numpy-discussion] GSoD - Technical Writter

Dashamir Hoxha
On Sun, May 19, 2019 at 10:36 PM Chris Barker - NOAA Federal <[hidden email]> wrote:

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

Sphinx is powerful, featurefull, and the standard doc system for Python. Let’s just stick with that.

But there are a LOT of themes available for Sphinx— I’m sure there are responsive ones  out there that could be used or adapted.


You might check out the bootstrap theme:


You are right, there are a lot of sphinx themes available: https://sphinx-themes.org/ and some of them are responsive. If such a theme takes care of everything this is great. But it may also be possible to use a jekyll theme for the homepage, and sphinx for the docs pages.

Regards,
Dashamir

P.s. I had a small confusion. I was subscribed to scipy-dev, but I posted by mistake to scipy-user, so I didn't read the replies there. Now I am subscribed to scipy-user as well.
 

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

Re: [Numpy-discussion] GSoD - Technical Writter

ralfgommers


On Tue, May 21, 2019 at 11:56 PM Dashamir Hoxha <[hidden email]> wrote:
On Sun, May 19, 2019 at 10:36 PM Chris Barker - NOAA Federal <[hidden email]> wrote:

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

Sphinx is powerful, featurefull, and the standard doc system for Python. Let’s just stick with that.

But there are a LOT of themes available for Sphinx— I’m sure there are responsive ones  out there that could be used or adapted.


You might check out the bootstrap theme:


You are right, there are a lot of sphinx themes available: https://sphinx-themes.org/ and some of them are responsive. If such a theme takes care of everything this is great. But it may also be possible to use a jekyll theme for the homepage, and sphinx for the docs pages.

Regards,
Dashamir

P.s. I had a small confusion. I was subscribed to scipy-dev, but I posted by mistake to scipy-user, so I didn't read the replies there. Now I am subscribed to scipy-user as well.

No worries. We can continue here with this conversation (if needed), but for new threads scipy-dev is the right place.

Cheers,
Ralf


_______________________________________________
SciPy-User mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/scipy-user