Description
We should consider implementing the documentation structure ideas described in this pycon 2017 talk and associated blog post:
https://www.youtube.com/watch?v=azf6yzuJt54
https://www.divio.com/en/blog/documentation/
My hope is that a more clearly defined documentation structure will help users identify how they can easily contribute to the documentation.
If people are interested and willing to commit the time to produce more how-to and tutorial content, I would volunteer to improve the documentation infrastructure and then help users get content into the documentation. Ideally, adding to the documentation would be as easy as adding a new jupyter notebook, markdown, or rst file to a source/howtos or source/tutorials directory. This would be a post-PVSC project.
Metadata
Metadata
Assignees
Type
Projects
Milestone
Relationships
Development
Participants
Activity
cwhanse commentedon Jan 9, 2020
@wholmgren what do you think about SunPy's documentation structure? Looking around at other projects to find a model for pvlib-python
wholmgren commentedon Jan 9, 2020
I like it. I suggest we pursue that refactoring once #846 is merged.
wholmgren commentedon Aug 12, 2020
I also like where MetPy is going here Unidata/MetPy#1457
kandersolar commentedon Oct 26, 2020
I just stumbled on this -- too late for this year I guess, but maybe next year: https://developers.google.com/season-of-docs
mikofski commentedon Oct 27, 2020
There's also outreachy:
Altho I believe Google Season of Docs recruits professional tech writers who probably need considerably less oversight than an intern.
kandersolar commentedon Oct 13, 2022
FYI the Divio link is now broken (but is still on archive.org). Here is an updated link that seems to have more detail than the original page did: https://documentation.divio.com/
I had a hard time understanding the differences between "Tutorials" and "How-To Guides" until I saw this table again:
So at a basic level, "how-to" guides are for people that are already writing code but want something to copy/paste for their specific task. Tutorials are for people who are looking to learn and the exact content doesn't need to be immediately applicable.
Anyway here is a first attempt at recategorizing our current docs with the Divio structure:
I propose this strategy to guide reworking our existing content and adding new content in the future:
Tutorialscould form the basis of future in-person tutorial sessions like the PVSC/PyData/PVPMC sessions.Tutorialssection. Callingget_solarpositionwith aDatetimeIndexfits in here; comparing solar position algorithms does not.Modeling Paradigms).With that strategy in mind, I see two main areas for improvement:
Tutorialand I'm not sure whether plot_interval_transposition_error is moreTutorialorExplanation. Additionally, the examples that skew closer toHow-Toshould be simplified. For example plot_ghi_transposition defines a helper function and demonstrates seasonal variation. I think the Divio approach would nix all that and just focus on getting from basic weather data to callingget_total_irradiance. Quantifying irradiance seasonality could be aTutorialcase study.sapm_cellandpvwatts_dcto predict DC power and compare with the real measured AC power. From there we could have a few other beginnerTutorialpages that build up to more complex (but still approachable) tasks like making a PVWatts emulator with ModelChain, then fetching a TMY and generating an 8760. Then have a separate "Advanced" section or something with the case studies. Perhaps a section for reproducing figures from scientific papers would be valuable.I declare this wall of text complete and solicit your feedback.
cwhanse commentedon Oct 25, 2022
+1 to the proposed strategy. The Intro Tutorial was intended for beginners, but I think our idea of a beginner was someone who already knew python and had some understanding of PV production modeling and needed to know how to use pvlib. I'd rather not try to teach PV power modeling by means of the pvlib docs, but we could copy the process figure from pvpmc.sandia.org if we think we need something.
I would like the API reference to become easier to use. Functions are not in alphabetical order, full paths are displayed (e.g.,
pvlib.clearsky.bird) and some methods are mixed in with base layer functions (pvlib.location.Location.get_clearsky) is in the "Clear sky" category.adriesse commentedon Oct 25, 2022
In terms of priorities, I would see API as number one and the rest as nice to have.
wholmgren commentedon Oct 28, 2022
@kanderso-nrel thanks for the careful analysis. It's hard for me to see how we go from here to there without a single enormous PR from a hero (i.e. you :) ). But maybe as a first step we could rewrite a few examples and create two categories.
The API reference worked a lot better before we adopted the pydata sphinx theme. For example, see 0.8.0 API docs. I haven't kept up with it, but maybe a newer version of pydata sphinx theme would help with general readability too.
kandersolar commentedon Oct 28, 2022
Agreed the new theme really makes a mess of the API reference. The problem is that, in the new theme, the left sidebar is for listing sub-pages and in-page sections go in the right sidebar, whereas the old theme put them both in the left sidebar. I will try to figure out some way to improve this.
Yeah. Maybe some alternative workflow would make sense here, like sending PRs to an intermediate (non-
master) branch to allow smaller piecemeal reviews without making a mess ofmasterin the meantime. I think more thought is needed about how specifically the docs would change, and then maybe a sensible implementation plan will emerge.