Consider formal design spec documents

[kandersolar]

Several aspects of pvlib's functionality and interface follow semi-official, but poorly documented, conventions. Here is a short list of cases where we have aligned, or would like to align some aspect of functions that are alternatives to each other in some sense:

• Back to basics for diffuse fraction functions #1753
• Behavior of calcparams and singlediode function could be improved #1626
• Consider allowing return_components in all transposition model functions #1553
• Inconsistencies in iotools #1245
  • and more broadly for iotools: map_variables, return data, metadata, requests.get(..., **kwargs), get/read

These conventions are great, and I'd like to see more of them. The problem is that they aren't easy to discover. I can think of a few possible benefits of making them more visible:

• Less likely to forget about a convention when implementing new features
• Might attract improvement ideas from community members who otherwise would not be aware of the conventions
• Serves as guidance in non-pvlib contexts (we know some commercial tools use pvlib as an example of "best practice")

I think the project would benefit from some central listing of these kinds of standards/conventions. The goal would be to provide consolidated documentation of aspects of pvlib's design that are too broad or high-level to put in any one function-level docstring. The Variables and Symbols page is an example of the kind of page I am imagining.

One thing that comes to mind is how some projects have their own version of PEPs (e.g. NumPy and Astropy), and there is also SPECs, although I don't know if that level of formality is necessary or desirable in our case.

[AdamRJensen]

I think this would be great! Developing this for the transposition/decomposition models would probably also require a good amount of cleanup/standardization of the current functions, which I suspect is unlikely to happen in the near future.

I posted an initial design spec in #1528

[cwhanse]

To the list above, I would add normalizing some parameter names #825 and function name patterns.