[Numpy-discussion] Season of Docs applications
Hi GSoD applicants, To start with, I want to thank all of you who applied! There's a lot of interest in helping improve NumPy's documentation and web presence, which is awesome to see. During the application phase, we have interacted with some of you already, and I will reach out to others over the next few days. I'm just writing this email to say thank you and to confirm that yes we did receive your application. Due to the volume of applications, it will be difficult to reach out personally to all of you (I'll do my best though!), hence this email. Really looking forward to what will happen next! Cheers, Ralf ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] numpy.org website redesign proposal
On Wed, Jul 17, 2019 at 8:43 AM Dashamir Hoxha wrote:
>
> On Wed, Jul 17, 2019 at 6:00 AM Ralf Gommers
> wrote:
>
>> Hi all,
>>
>> I just opened https://github.com/numpy/numpy/pull/14032, which contains
>> a NEP for a redesign of the NumPy website (just the top-level site, not the
>> docs). The part that most warrants discussion is probably the translation
>> part. Additions to the NEP from anyone who has useful experiences with
>> managing translations like that would be quite welcome.
>>
>> There's a couple of motivations for writing this as a NEP:
>> 1. Ensure that we're all on the same page before doing quite a bit of work
>> 2. Empowering people who have offered help with the website to go ahead
>> and make changes. We got a few offers of help from people who are new to
>> the project, which is awesome. I want to make sure they feel comfortable
>> making some decisions.
>> 3. Pushing forward with the website redesign now prepares the ground for
>> GSoD, where we have tech writers and people with marketing skills that I
>> hope will generate much better content than we have now. Integrating that
>> content is much easier in a well-designed site than into the current Sphinx
>> site.
>>
>> I also will start inviting our new volunteers to the NumPy web team, so
>> they have the permissions needed to work on the website repo.
>>
>
> First of all, choosing a few existing sites as examples to follow is the
> best thing to do. I like all the three sites selected by Ralf, especially
> that of Jupiter and Julia. Having such examples makes our job much easier
> (and also reduces our choices and discussions about possible choices).
>
> Indeed, if we want to make our site similar to Jupiter, we just fork it (
> https://github.com/jupyter/jupyter.github.io) and customize its content.
> If we want to make it similar to Julia, we just fork it:
> https://github.com/JuliaLang/www.julialang.org Both of them are in Jekyll
> and markdown, so this is the only choice (unless we want to make our site
> similar to that of pandas, which is built with sphinx). We admit that none
> of us is good as a web designer, so following the example of a nice website
> is the best way to go.
>
That could be an idea. Not sure it's much less work (we'd have to change
all stying, graphics and text anyway), but it may be. I think
> I don't understand the need/requirement for translation or i18n.
>
The need is simple: for many of our users (the majority I think), English
is not the first language. Many people are prevented from learning about
NumPy effectively. A few pages in their own language goes a long way to
helping them. Also, we're likely missing out on contributions due to this.
I've had a number of people tell me that this is a significant barrier.
None of the sites that we are considering as examples have it, and I have
> not seen any other sites that have it. Maybe I am missing something. Can
> someone show an example of a website with translation?
>
AstroPy is wanting to do this too IIRC. Most widely used commercial
software/platforms have this (because they can measure the impact of
translations in sales - it matters). Examples: https://hortonworks.com/,
https://aws.amazon.com/.
An example from an open source project:
https://www.tensorflow.org/guide/extend/bindings ("language button" at the
top, changes to Chinese).
I'd like to try it and see if we can make it work with low maintenance
overhead. If we can't figure out the workflow to make the overhead low
enough, then that's a no-go. But I think with today's tools it's possible.
Cheers,
Ralf
> By the way, I know that the docs are not the topic of this NEP, but I
> think that we should follow the good examples for the documentation of the
> code as well. For example Jupiter and Julia:
> - https://jupyter.org/documentation
> - https://docs.julialang.org/en/v1/
>
> Regards,
> Dashamir
> ___
> NumPy-Discussion mailing list
> NumPy-Discussion@python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>
___
NumPy-Discussion mailing list
NumPy-Discussion@python.org
https://mail.python.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Helping with website improvements
On Wed, Jul 17, 2019 at 7:29 AM Dashamir Hoxha wrote: > > > On Wed, Jul 17, 2019 at 6:11 AM Ralf Gommers > wrote: > >> >>> Has anybody tried Katacoda before: >>> https://www.katacoda.com/courses/python/playground ? >>> >> >> I haven't heard of it before. Looks cool. Seems to run on Docker, so >> would require some infrastructure. If it's something we could get from a >> static site, then it may be worth considering. Could you summarize what it >> would require? >> > > The infrastructure is supplied by Katacoda, we don't need to run or > maintain any server (although I don't think this would be a big problem). > And it is free. The only limitation is that the duration of the training > session for a student is 1 hour (and then he can reload the browser and > start a fresh session). If enterprises or training companies would like to > lift this limitation, they have to contact them. > > Building an interactive tutorial is very easy and everybody can learn it > in a short time. The code of the tutorial is just a bunch of json and > markdown files (for the configuration of the environment and for the steps > of the tutorial). It can be saved on your preferred git repository (GitHub, > GitLab, Bitbacket, etc.) and katacoda pulls it from there and builds the > tutorial environment (docker image). Here is a minimal (hello world) > example: > https://github.com/dashohoxha/katacoda-scenarios/tree/master/hello-world You > also need to set a webhook on the repository, so that whenever you make > some changes (commits) katacoda is notified to refresh the content of the > tutorial. > That sounds good to me. I believe SymPy is also pretty happy with their interactive terminal embedded in their website. Could you create a new issue on https://github.com/numpy/numpy.org/issues? It would be good to start keeping track of website improvement ideas - ideas in mailing list threads tend to get lost eventually. Thanks, Ralf ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] numpy.org website redesign proposal
On Wed, Jul 17, 2019 at 6:00 AM Ralf Gommers wrote: > Hi all, > > I just opened https://github.com/numpy/numpy/pull/14032, which contains a > NEP for a redesign of the NumPy website (just the top-level site, not the > docs). The part that most warrants discussion is probably the translation > part. Additions to the NEP from anyone who has useful experiences with > managing translations like that would be quite welcome. > > There's a couple of motivations for writing this as a NEP: > 1. Ensure that we're all on the same page before doing quite a bit of work > 2. Empowering people who have offered help with the website to go ahead > and make changes. We got a few offers of help from people who are new to > the project, which is awesome. I want to make sure they feel comfortable > making some decisions. > 3. Pushing forward with the website redesign now prepares the ground for > GSoD, where we have tech writers and people with marketing skills that I > hope will generate much better content than we have now. Integrating that > content is much easier in a well-designed site than into the current Sphinx > site. > > I also will start inviting our new volunteers to the NumPy web team, so > they have the permissions needed to work on the website repo. > First of all, choosing a few existing sites as examples to follow is the best thing to do. I like all the three sites selected by Ralf, especially that of Jupiter and Julia. Having such examples makes our job much easier (and also reduces our choices and discussions about possible choices). Indeed, if we want to make our site similar to Jupiter, we just fork it ( https://github.com/jupyter/jupyter.github.io) and customize its content. If we want to make it similar to Julia, we just fork it: https://github.com/JuliaLang/www.julialang.org Both of them are in Jekyll and markdown, so this is the only choice (unless we want to make our site similar to that of pandas, which is built with sphinx). We admit that none of us is good as a web designer, so following the example of a nice website is the best way to go. I don't understand the need/requirement for translation or i18n. None of the sites that we are considering as examples have it, and I have not seen any other sites that have it. Maybe I am missing something. Can someone show an example of a website with translation? By the way, I know that the docs are not the topic of this NEP, but I think that we should follow the good examples for the documentation of the code as well. For example Jupiter and Julia: - https://jupyter.org/documentation - https://docs.julialang.org/en/v1/ Regards, Dashamir ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
Re: [Numpy-discussion] Helping with website improvements
On Wed, Jul 17, 2019 at 6:11 AM Ralf Gommers wrote: > >> Has anybody tried Katacoda before: >> https://www.katacoda.com/courses/python/playground ? >> > > I haven't heard of it before. Looks cool. Seems to run on Docker, so would > require some infrastructure. If it's something we could get from a static > site, then it may be worth considering. Could you summarize what it would > require? > The infrastructure is supplied by Katacoda, we don't need to run or maintain any server (although I don't think this would be a big problem). And it is free. The only limitation is that the duration of the training session for a student is 1 hour (and then he can reload the browser and start a fresh session). If enterprises or training companies would like to lift this limitation, they have to contact them. Building an interactive tutorial is very easy and everybody can learn it in a short time. The code of the tutorial is just a bunch of json and markdown files (for the configuration of the environment and for the steps of the tutorial). It can be saved on your preferred git repository (GitHub, GitLab, Bitbacket, etc.) and katacoda pulls it from there and builds the tutorial environment (docker image). Here is a minimal (hello world) example: https://github.com/dashohoxha/katacoda-scenarios/tree/master/hello-world You also need to set a webhook on the repository, so that whenever you make some changes (commits) katacoda is notified to refresh the content of the tutorial. Regards, Dashamir ___ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
