Merge pull request #822 from google-deepmind:fabianp-patch-2

PiperOrigin-RevId: 610119017

docs/development.md

@@ -1,8 +1,7 @@
 # 🛠️ Development
 
-Optax welcomes contributions from the open-source community. This can include
-issues, bug reports, questions, design documents, pull requests, or any other
-input to the project.
+We welcome contributions to Optax! Whether you have a bug report, a question,
+a feature suggestion, or code to share, your input is valuable.
 
 ## How to Contribute
 
@@ -13,22 +12,36 @@ discussion on the best way to land new features, and can also provide
 opportunities for collaborations with other contributors.
 
 Some more details on contributing code are provided in the
-[CONTRIBUTING.md](https://github.com/deepmind/optax/blob/main/CONTRIBUTING.md)
+[CONTRIBUTING.md](https://github.com/google-deepmind/optax/blob/main/CONTRIBUTING.md)
 file in the source tree.
 
+**Need ideas?** If you would like to get started with contributing to Optax, but do not know
+what to start working on, check out our selection of [*good first issues*](https://github.com/google-deepmind/optax/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+
+
+## Improving the documentation
+
+Documentation is key, and we're particularly happy to accept documentation improvements.
+
+Our documentation is written in [Sphinx](https://www.sphinx-doc.org/en/master/). You can
+build the documentation locally as follows:
+
+1. **Install Requirements**: `pip install .[docs]`
+2. **Build the Docs**: From the `docs` folder, run:
+   * `make html` (builds everything)
+   * `make html-noplot` (faster, skips running examples)
+
 
 (inclusion_criteria)=
 ## Inclusion Criteria
 
-We only consider well-established algorithms for inclusion in the main `optax`
-package. A rule of thumb is at least 2 years since publication, 100+ citations,
-and wide usefulness. A small modification of an existing algorithm that provides
-a clear-cut improvement on a widely-used method will also be considered for
-inclusion.
+To ensure Optax remains a focused and high-quality library, we have specific guidelines for including algorithms in the main `optax` package:
+
+1. **Established**: Algorithms should generally be published for at least 2 years, well-cited (100+ citations), and demonstrate broad utility.
+2. **Significant Improvement**: Minor modifications will be considered if they offer clear advantages over widely used methods.
+
+If your algorithm doesn't meet the main package criteria, the {doc}`api/contrib` directory is perfect for sharing innovative work.
 
-Algorithms that don't meet these criteria should instead be submitted to the
-{doc}`api/contrib` directory. When in doubt, we recommend submitting new
-algorithms to this directory.
 
 
 #### Design Documents
@@ -40,7 +53,7 @@ provide input and find the best way to land new features and also provides a
 reference for future users to understand how the library works.
 
 For an example of this, see the following
-[[RFC] Proposal for complex-valued optimization in Optax](https://gist.github.com/wdphy16/118aef6fb5f82c49790d7678cf87da29) authored by [Dian [Wu](https://github.com/wdphy16) which led to the addition of improved [complex numbers](https://optax.readthedocs.io/en/latest/api/contrib.html?complex-valued-optimization#complex-valued-optimization) support in Optax.
+[[RFC] Proposal for complex-valued optimization in Optax](https://gist.github.com/wdphy16/118aef6fb5f82c49790d7678cf87da29) authored by [Dian Wu](https://github.com/wdphy16) which led to the addition of improved [complex numbers](https://optax.readthedocs.io/en/latest/api/contrib.html?complex-valued-optimization#complex-valued-optimization) support in Optax.
 
 
 #### Contributor License Agreement
@@ -55,21 +68,6 @@ You generally only need to submit a CLA once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.
 
-#### Ideas for Contributions
-
-If you would like to get started with contributing to Optax, but do not know
-what to start working on, a selection of *"good first issues"* for new
-contributors are given in the
-[issue tracker](https://github.com/deepmind/optax/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue).
-Ideas for good starter contributions are also welcomed.
-
-#### Improving the documentation
-
-If you would like to help contributing to the documentation, install the
-required packages by running `pip install .[docs]`.
-Then, to build the docs, from the docs folder, run `make html` to build all docs
-and notebooks or `make html-noplot` to build the docs without executing
-the notebooks (much faster).
 
 ## Core Maintainers