<div dir="ltr"><div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, May 17, 2019 at 6:57 PM Dashamir Hoxha <<a href="mailto:dashohoxha@gmail.com">dashohoxha@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>On Fri, May 17, 2019 at 2:54 PM Ralf Gommers <<a href="mailto:ralf.gommers@gmail.com" target="_blank">ralf.gommers@gmail.com</a>> wrote:<br></div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>Hi Dashamir,</div><div><br></div><div>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. </div></div></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div><br></div><div>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.</div></div></blockquote><div> </div><div>Thanks for your encouraging message, Ralf.<br></div><div><br></div><div><div>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.</div><div>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.</div></div></div></div></blockquote><div><br></div><div>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 (<a href="http://scipy.org">scipy.org</a>, <a href="http://docs.scipy.org">docs.scipy.org</a>) could be moved to Jekyll or Hugo for a more modern look - this will actually be beneficial.<br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div><div><br></div><div>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: <a href="https://github.com/RunestoneInteractive/RunestoneComponents" target="_blank">https://github.com/RunestoneInteractive/RunestoneComponents</a></div></div></div></div></blockquote><div><br></div><div>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.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div><div><br></div><div>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.</div></div></div></div></blockquote><div><br></div><div>Yes, there's <a href="https://scipy-lectures.org/">https://scipy-lectures.org/</a> for example. Guiding users effectively to all existing resources will be a major step forward.</div><div><br></div><div>Cheers,</div><div>Ralf</div><div><br></div></div></div></div>