Improve Brightway Documentation

[michaelweinold]

"The documentation needs documentation." a Bellevue Linux Users Group member, 2005

⚠️ This issue is only for organizing tasks related to the hackathon setup. For actual issues related to documentation, compare the two relevant repositories:

https://github.com/brightway-lca/brightway-documentation-jupyter-book https://github.com/brightway-lca/brightway-documentation-readthedocs

ℹ️ Hackathon Information

As the functionality and the user base of Brightway continues to grow, the documentation must grow too. The current vision is to split up the documentation into:

1. A user-friendly, interactive documentation based on Jupyter Books. This includes a comprehensive "getting started" page and has the ability to run small snippets of Brightway code in-browser.
2. A developer-focused detailed API documentation based on Sphinx and hosted at readthedocs.com. This takes in-code documentation, such as function docstrings to generate a detailed outline.

🗓 Hackathon Schedule

• [x] "what does the perfect documentation look like?"

☑️ Hackathon Agenda

Technical Documentation

BEFORE the Hackathon

• [x] create readthedocs.org account
• [x] give multiple users (Brightway developers) access to readthedocs.org site

DURING the Hackathon

• [x] create single documentation for multiple packages (bw_agg, bw_calc, etc.)
• [x] move existing Sphinx documetation from https://2.docs.brightway.dev/technical/* to brightway.readthedocs.org
• [x] create issues in the respective repos if documentation is missing

User Documentation

BEFORE the Hackathon

• [ ] move remaining pages to existing Jupyter Book
• [x] create setup ("getting started with Jupyter Books") documentation for hackathon participants

DURING the Hackathon

• [ ] create outline of documentation
• [ ] set up in-browser code execution (binder.org or colabs or hub.brightway.dev)

🌐 Useful Links

Brightway Strategic Development Plan Brightway Jupyter Books Documentation Diataxis Documentation Framework documentation-as-a-way-to-build-community Gallery of Jupyter Books

[michaelweinold]

Compare:

https://github.com/brightway-lca/jupyter-book-brightway-documentation/issues/1

[shirubana]

Not sure if useful, but I really like the template that pvlib implemented and this pull request shows the changes in my repo which looked similar to brightways to obtain that sidebar and topbar division of content, as well as the Gallery of journal examples.

[michaelweinold]

Not sure if useful, but I really like the template that pvlib implemented and this pull request shows the changes in my repo which looked similar to brightways to obtain that sidebar and topbar division of content, as well as the Gallery of journal examples.

This readthedocs page looks great - we'll make sure to adapt our prototoype to reflect the layout.

[shirubana]

Also as an afterthought -- I don't see this in an obvious manner in the current documentation, so it'd be great to include a What's new with every sub package release that feeds into the main whats new.

[michaelweinold]

Also as an afterthought -- I don't see this in an obvious manner in the current documentation, so it'd be great to include a What's new with every sub package release that feeds into the main whats new.

Agreed! There will be more structured changelog template also. Compare also the https://gitter.im/brightway-lca/announcements Gitter room for announcements of this nature.

[michaelweinold]

Brainstorming session "what would the worst documentation look like"?

[michaelweinold]

All further tasks are tracked in the documentation and the training repos: https://github.com/brightway-lca/brightway-documentation/issues https://github.com/brightway-lca/brightway-training/issues

[michaelweinold]

Brainstorming session result:

Documentation Hackathon the worst possible documentation.pdf