| Number | 3 |
| Title | Brightway Documentation |
| Status | Proposed |
| Type | Guidelines |
| Proposed By | Michael Weinold, Chris Mutel |
| Editor | Tomas Navarrete Gutierrez |
| Created | 2022-10-09 |
| Last updated | 2023-01-09 |
| Version | 4 |
As the functionality and user base of Brightway continues to grow, the documentation must grow too. As part of the Brightway Strategic Development Plan (F1-F4), the documentation should be made compliant with the Diataxis framework for technical documentation. It should be split up into a user-focused interactive website containing tutorials and into a more developer-focused website containing the API reference as well as a gallery of how-to guides and some theoretical information on life-cycle assessment.
Currently (prior to the 2022 Brightcon Hackathon), a Google search for "Brightway documentation" returnes:
| website |
|---|
| https://2.docs.brightway.dev/ |
| https://brightway.dev/ (redirects to the above) |
| https://brightway-docs.readthedocs.io/ |
Various notebooks written as part of training events and seminars are further collected at https://github.com/brightway-lca/brightway2/tree/master/notebooks. Some are outdated (Jupyter Notebook version) and can no longer be viewed in GitHub.
The primary documentation at https://2.docs.brightway.dev/ is difficult to navigate for first-time users. It does not differentiate clearly between different user needs and offers not interactivity.
The Diataxis framework was created and developed by Daniele Procida during his tenure at Divio. It formalizes different types of technical documentation according to the different needs of users. It is widely adopted in software development (e.g. at Canonical, Cloudflare, Google, etc.).
| serve our study | serve our work | |
|---|---|---|
| practical steps | Tutorials learning-oriented |
How-To Guides task-oriented |
| theoretical knowledge | Explanation understanding-oriented |
Reference information-oriented |
Table 1: The Diataxis framework
The framework distinguishes based on the needs of the user: The purpose of a tutorial is to provide a successful learning experience. The purpose of a how-to guide is to to help the user accomplish a task.
🌐 Diataxis documentation: Tutorials vs How-To Guides
The documentation for Brightway shall be structured to conform to the Diataxis framework:
| serve our study | serve our work | |
|---|---|---|
| practical steps | Tutorials (=Training) All tutorials at training.brightway.dev |
How-To Guides "Gallery" at documentation.brightway.dev |
| theoretical knowledge | Explanation "LCA" at documentation.brightway.dev |
Reference "API Reference" at documentation.brightway.dev |
Table 2: The Brightway implementation of the Diataxis framework
This shall contain the API reference for the various Brightway modules (bw_agg, bw_calc, bw_data, ...). This is compiled automatically from the function docstrings by the Sphinx package.
This shall include the mathematical formalism of life-cycle assessment, some theory of matrix multiplication, etc. The exact contents are to be discussed based on the "Scope of the Documentation" section.
This shall include the growing number of high-quality interactive Jupyter Notebooks already available at brightway-lca/brightway2/notebooks, as well as some of the notebooks collected as part of the 2022 Brightcon Hackathon.
This shall contain self-contained examples of Brightway code. This is supported by the "Gallery" functionality of the pydata Sphinx template, as implemented by pvlib.
Contributors familiar with Sphinx, shall fork the brightway-lca/brightway-documentation repository, add their contributions and create a pull request.
Otherwise, contributors shall open a discussion item in the respective repository.
Contributors familiar with Jupyter Book, shall fork the brightway-lca/brightway-training, add their contributions and create a pull request.
Otherwise, contributors shall open a discussion item in the respective repository.
The pydata Sphinx template in combination with readthedocs.org and the Jupyter Book template in combintaion with GitHub pages are free and open source, future-proof options of hosting documentation.
- Future proof established standard of documenting code
- Lower entry barriers for users with little experience in Python
- ..?
Expand the current documentation and simply link to a directory containing Jupyter notebooks. Keep the current separation between "API Reference" and "Introduction and key Concepts (etc.)", instead of adopting the four Diataxis categories.
Compare the open issues in the respective repositories:
N/A
Prototypes of documentation.brightway.dev and training.brightway.dev were developed as part of the Brightcon 2022 Hackathon.
Work on the prototypes will continue until they are deemed ready for review by the BEP authors. The goal is to reach a level of completeness comparable to that of the pvlib documentation.
- BEP-0003 Discussion on GitHub
- The Gitter
documentationchannel - F1-F4 of the Strategic Development Plan
- The Brightcon 2022 Hackathon, with results of the brainstorming sessions documented in #10 Improve Brightway Documentation
- Issues in the respective repositories:
Compare also the Development Meeting Minutes in the brightway-documentation repo.
N/A