335 lines
14 KiB
ReStructuredText
335 lines
14 KiB
ReStructuredText
===================================
|
|
NEP 28 — numpy.org website redesign
|
|
===================================
|
|
|
|
:Author: Ralf Gommers <ralf.gommers@gmail.com>
|
|
:Author: Joe LaChance <joe@boldmetrics.com>
|
|
:Author: Shekhar Rajak <shekharrajak.1994@gmail.com>
|
|
:Status: Accepted
|
|
:Type: Informational
|
|
:Created: 2019-07-16
|
|
:Resolution: https://mail.python.org/pipermail/numpy-discussion/2019-August/079889.html
|
|
|
|
|
|
Abstract
|
|
--------
|
|
|
|
NumPy is the fundamental library for numerical and scientific computing with
|
|
Python. It is used by millions and has a large team of maintainers and
|
|
contributors. Despite that, its `numpy.org <http://numpy.org>`_ website has
|
|
never received the attention it needed and deserved. We hope and intend to
|
|
change that soon. This document describes ideas and requirements for how to
|
|
design a replacement for the current website, to better serve the needs of
|
|
our diverse community.
|
|
|
|
At a high level, what we're aiming for is:
|
|
|
|
- a modern, clean look
|
|
- an easy to deploy static site
|
|
- a structure that's easy to navigate
|
|
- content that addresses all types of stakeholders
|
|
- Possible multilingual translations / i18n
|
|
|
|
This website serves a couple of roles:
|
|
|
|
- it's the entry point to the project for new users
|
|
- it should link to the documentation (which is hosted separately, now on
|
|
http://docs.scipy.org/ and in the near future on http://numpy.org/doc).
|
|
- it should address various aspects of the project (e.g. what NumPy is and
|
|
why you'd want to use it, community, project organization, funding,
|
|
relationship with NumFOCUS and possibly other organizations)
|
|
- it should link out to other places, so every type of stakeholder
|
|
(beginning and advanced user, educators, packagers, funders, etc.)
|
|
can find their way
|
|
|
|
|
|
Motivation and Scope
|
|
--------------------
|
|
|
|
The current numpy.org website has almost no content and its design is poor.
|
|
This affects many users, who come there looking for information. It also
|
|
affects many other aspects of the NumPy project, from finding new contributors
|
|
to fundraising.
|
|
|
|
The scope of the proposed redesign is the top-level numpy.org site, which
|
|
now contains only a couple of pages and may contain on the order of ten
|
|
pages after the redesign. Changing the documentation (user guide, reference
|
|
guide, and some other pages in the NumPy Manual) is out of scope for
|
|
this proposal.
|
|
|
|
|
|
Detailed description
|
|
--------------------
|
|
|
|
User Experience
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Besides the NumPy logo, there is little that can or needs to be kept from the
|
|
current website. We will rely to a large extent on ideas and proposals by the
|
|
designer(s) of the new website.
|
|
|
|
As reference points we can use the `Jupyter website <https://jupyter.org/>`_,
|
|
which is probably the best designed site in our ecosystem, and the
|
|
`QuantEcon <https://quantecon.org>`_ and `Julia <https://julialang.org>`_
|
|
sites which are well-designed too.
|
|
|
|
The Website
|
|
~~~~~~~~~~~
|
|
|
|
A static site is a must. There are many high-quality static site generators.
|
|
The current website uses Sphinx, however that is not the best choice - it's
|
|
hard to theme and results in sites that are too text-heavy due to Sphinx'
|
|
primary aim being documentation.
|
|
|
|
The following should be considered when choosing a static site generator:
|
|
|
|
1. *How widely used is it?* This is important when looking for help maintaining
|
|
or improving the site. More popular frameworks are usually also better
|
|
maintained, so less chance of bugs or obsolescence.
|
|
2. *Ease of deployment.* Most generators meet this criterion, however things
|
|
like built-in support for GitHub Pages helps.
|
|
3. *Preferences of who implements the new site.* Everyone has their own
|
|
preferences. And it's a significant amount of work to build a new site.
|
|
So we should take the opinion of those doing the work into account.
|
|
|
|
Traffic
|
|
```````
|
|
|
|
The current site receives on the order of 500,000 unique visitors per month.
|
|
With a redesigned site and relevant content, there is potential for visitor
|
|
counts to reach 5-6 million -- a similar level as
|
|
`scipy.org <http://scipy.org>`_ or `matplotlib.org <http://matplotlib.org>`_ --
|
|
or more.
|
|
|
|
Possible options for static site generators
|
|
```````````````````````````````````````````
|
|
|
|
1. *Jekyll.* This is a well maintained option with 855 Github contributors,
|
|
with contributions within the last month. Jekyll is written in Ruby, and
|
|
has a simple CLI interface. Jekyll also has a large directory of
|
|
`themes <https://jekyllthemes.io>`__, although a majority cost money.
|
|
There are several themes (`serif <https://jekyllthemes.io/theme/serif>`_,
|
|
`uBuild <https://jekyllthemes.io/theme/ubuild-jekyll-theme>`_,
|
|
`Just The Docs <https://jekyllthemes.io/theme/just-the-docs>`_) that are
|
|
appropriate and free. Most themes are likely responsive for mobile, and
|
|
that should be a requirement. Jekyll uses a combination of liquid templating
|
|
and YAML to render HTML, and content is written in Markdown. i18n
|
|
functionality is not native to Jekyll, but can be added easily.
|
|
One nice benefit of Jekyll is that it can be run automatically by GitHub
|
|
Pages, so deployment via a CI system doesn't need to be implemented.
|
|
2. *Hugo.* This is another well maintained option with 554 contributors, with
|
|
contributions within the last month. Hugo is written in Go, and similar to
|
|
Jekyll, has a simple to use CLI interface to generate static sites. Again,
|
|
similar to Jekyll, Hugo has a large directory of
|
|
`themes <https://themes.gohugo.io>`_. These themes appear to be free,
|
|
unlike some of Jekyll's themes.
|
|
(`Sample landing page theme <https://themes.gohugo.io/hugo-hero-theme>`_,
|
|
`docs theme <https://themes.gohugo.io/hugo-whisper-theme>`_). Hugo uses Jade
|
|
as its templating language, and content is also written in Markdown. i18n
|
|
functionality is native to Hugo.
|
|
3. *Docusaurus.* Docusaurus is a responsive static site generator made by Facebook.
|
|
Unlike the previous options, Docusaurus doesn't come with themes, and thus we
|
|
would not want to use this for our landing page. This is an excellent docs
|
|
option written in React. Docusaurus natively has support for i18n (via
|
|
Crowdin_), document versioning, and document search.
|
|
|
|
Both Jekyll and Hugo are excellent options that should be supported into the
|
|
future and are good choices for NumPy. Docusaurus has several bonus features
|
|
such as versioning and search that Jekyll and Hugo don't have, but is likely
|
|
a poor candidate for a landing page - it could be a good option for a
|
|
high-level docs site later on though.
|
|
|
|
Deployment
|
|
~~~~~~~~~~
|
|
|
|
There is no need for running a server, and doing so is in our experience a
|
|
significant drain on the time of maintainers.
|
|
|
|
1. *Netlify.* Using netlify is free until 100GB of bandwidth is used. Additional
|
|
bandwidth costs $20/100GB. They support a global CDN system, which will keep
|
|
load times quick for users in other regions. Netlify also has Github integration,
|
|
which will allow for easy deployment. When a pull request is merged, Netlify
|
|
will automatically deploy the changes. DNS is simple, and HTTPS is also supported.
|
|
2. *Github Pages.* Github Pages also has a 100GB bandwidth limit, and is unclear if
|
|
additional bandwidth can be purchased. It is also unclear where sites are deployed,
|
|
and should be assumed sites aren't deployed globally. Github Pages has an easy to
|
|
use CI & DNS, similar to Netlify. HTTPS is supported.
|
|
3. *Cloudflare.* An excellent option, additional CI is likely needed for the same
|
|
ease of deployment.
|
|
|
|
All of the above options are appropriate for the NumPy site based on current
|
|
traffic. Updating to a new deployment strategy, if needed, is a minor amount of
|
|
work compared to developing the website itself. If a provider such as
|
|
Cloudflare is chosen, additional CI may be required, such as CircleCI, to
|
|
have a similar deployment to GitHub Pages or Netlify.
|
|
|
|
Analytics
|
|
~~~~~~~~~
|
|
|
|
It's beneficial to maintainers to know how many visitors are coming to
|
|
numpy.org. Google Analytics offers visitor counts and locations. This will
|
|
help to support and deploy more strategically, and help maintainers
|
|
understand where traffic is coming from.
|
|
|
|
Google Analytics is free. A script, provided by Google, must be added to the home page.
|
|
|
|
Website Structure
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
We aim to keep the first version of the new website small in terms of amount
|
|
of content. New pages can be added later on, it's more important right now to
|
|
get the site design right and get some essential information up. Note that in
|
|
the second half of 2019 we expect to get 1 or 2 tech writers involved in the
|
|
project via Google Season of Docs. They will likely help improve the content
|
|
and organization of that content.
|
|
|
|
We propose the following structure:
|
|
|
|
0. Front page: essentials of what NumPy is (compare e.g. jupyter.org), one or
|
|
a couple key user stories (compare e.g. julialang.org)
|
|
1. Install
|
|
2. Documentation
|
|
3. Array computing
|
|
4. Community
|
|
5. Learning
|
|
6. About Us
|
|
7. Contribute
|
|
8. Donate
|
|
|
|
There may be a few other pages, e.g. a page on performance, that are linked
|
|
from one of the main pages.
|
|
|
|
Stakeholder Content
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
This should have as little content as possible *within the site*. Somewhere
|
|
on the site we should link out to content that's specific to:
|
|
|
|
- beginning users (quickstart, tutorial)
|
|
- advanced users
|
|
- educators
|
|
- packagers
|
|
- package authors that depend on NumPy
|
|
- funders (governance, roadmap)
|
|
|
|
Translation (multilingual / i18n)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
NumPy has users all over the world. Most of those users are not native
|
|
English speakers, and many don't speak English well or at all. Therefore
|
|
having content in multiple languages is potentially addressing a large unmet
|
|
need. It would likely also help make the NumPy project more diverse and
|
|
welcoming.
|
|
|
|
On the other hand, there are good reasons why few projects have a
|
|
multi-lingual site. It's potentially a lot of extra work. Extra work for
|
|
maintainers is costly - they're already struggling to keep up with the work
|
|
load. Therefore we have to very carefully consider whether a multi-lingual
|
|
site is feasible and weight costs and benefits.
|
|
|
|
We start with an assertion: maintaining translations of all documentation, or
|
|
even the whole user guide, as part of the NumPy project is not feasible. One
|
|
simply has to look at the volume of our documentation and the frequency with
|
|
which we change it to realize that that's the case. Perhaps it will be
|
|
feasible though to translate just the top-level pages of the website. Those
|
|
do not change very often, and it will be a limited amount of content (order
|
|
of magnitude 5-10 pages of text).
|
|
|
|
We propose the following requirements for adding a language:
|
|
|
|
- The language must have a dedicated maintainer
|
|
- There must be a way to validate content changes (e.g. a second
|
|
maintainer/reviewer, or high quality language support in a freely
|
|
available machine translation tool)
|
|
- The language must have a reasonable size target audience (to be
|
|
assessed by the NumPy maintainers)
|
|
|
|
Furthermore we propose a policy for when to remove support for a language again
|
|
(preferably by hiding it rather than deleting content). This may be done when
|
|
the language no longer has a maintainer, and coverage of translations falls
|
|
below an acceptable threshold (say 80%).
|
|
|
|
Benefits of having translations include:
|
|
|
|
- Better serve many existing and potential users
|
|
- Potentially attract a culturally and geographically more diverse set of contributors
|
|
|
|
The tradeoffs are:
|
|
|
|
- Cost of maintaining a more complex code base
|
|
- Cost of making decisions about whether or not to add a new language
|
|
- Higher cost to making content changes, creates work for language maintainers
|
|
- Any content change should be rolled out with enough delay to have translations in place
|
|
|
|
Can we define a small enough set of pages and content that it makes sense to do this?
|
|
Probably yes.
|
|
|
|
Is there an easy to use tool to maintain translations and add them to the website?
|
|
To be discussed - it needs investigating, and may depend on the choice of static site
|
|
generator. One potential option is Crowdin_, which is free for open source projects.
|
|
|
|
|
|
Style and graphic design
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Beyond the "a modern, clean look" goal we choose to not specify too much. A
|
|
designer may have much better ideas than the authors of this proposal, hence we
|
|
will work with the designer(s) during the implementation phase.
|
|
|
|
The NumPy logo could use a touch-up. The logo widely recognized and its colors and
|
|
design are good, however the look-and-feel is perhaps a little dated.
|
|
|
|
|
|
Other aspects
|
|
~~~~~~~~~~~~~
|
|
|
|
A search box would be nice to have. The Sphinx documentation already has a
|
|
search box, however a search box on the main site which provides search results
|
|
for the docs, the website, and perhaps other domains that are relevant for
|
|
NumPy would make sense.
|
|
|
|
|
|
Backward compatibility
|
|
----------------------
|
|
|
|
Given a static site generator is chosen, we will migrate away from Sphinx for
|
|
numpy.org (the website, *not including the docs*). The current deployment can
|
|
be preserved until a future deprecation date is decided (potentially based on
|
|
the comfort level of our new site).
|
|
|
|
All site generators listed above have visibility into the HTML and Javascript
|
|
that is generated, and can continue to be maintained in the event a given
|
|
project ceases to be maintained.
|
|
|
|
|
|
Alternatives
|
|
------------
|
|
|
|
Alternatives we considered for the overall design of the website:
|
|
|
|
1. *Update current site.* A new Sphinx theme could be chosen. This would likely
|
|
take the least amount of resources initially, however, Sphinx does not have
|
|
the features we are looking for moving forward such as i18n, responsive design,
|
|
and a clean, modern look.
|
|
Note that updating the docs Sphinx theme is likely still a good idea - it's
|
|
orthogonal to this NEP though.
|
|
2. *Create custom site.* This would take the most amount of resources, and is
|
|
likely to have additional benefit in comparison to a static site generator.
|
|
All features would be able to be added at the cost of developer time.
|
|
|
|
|
|
Discussion
|
|
----------
|
|
|
|
Mailing list thread discussing this NEP: TODO
|
|
|
|
|
|
References and Footnotes
|
|
------------------------
|
|
.. _Crowdin: https://crowdin.com/pricing#annual
|
|
|
|
Copyright
|
|
---------
|
|
|
|
This document has been placed in the public domain.
|