numpy · rgommers · Aug 6, 2019 · Jul 17, 2019 · Jul 20, 2019 · Aug 5, 2019
diff --git a/doc/neps/nep-0028-website-redesign.rst b/doc/neps/nep-0028-website-redesign.rst
@@ -0,0 +1,334 @@
+===================================
+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: Draft
+:Type: Informational
+:Created: 2019-07-16
+:Resolution: <url> (required for Accepted | Rejected | Withdrawn)
+
+
+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 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 benefical 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.