Standardize authorship attribution

[OriolAbril]

Right now it's not clear how authors of examples should claim authorship so they can get proper credit. There are several alternatives around:

• Table with version history: https://oriolabril.github.io/pymc3/pymc-examples/examples/generalized_linear_models/GLM-robust-with-outlier-detection.html?highlight=author#notes
• Authors on top of the blogpost: https://oriolabril.github.io/pymc3/pymc-examples/examples/getting_started.html?highlight=author, https://oriolabril.github.io/pymc3/pymc-examples/examples/case_studies/mediation_analysis.html?highlight=author. This would probably be compatible with ablog authorship. But I (Oriol) wasn't planning on exposing the page grouping examples by author and don't really see the use for it in this particular case.
• Authorship description at the end of the example, listing also authors of major updates, but not those of minor updates/rerunning of notebooks. https://oriolabril.github.io/pymc3/pymc-examples/examples/survival_analysis/bayes_param_survival_pymc3.html?highlight=author#authors or https://oriolabril.github.io/pymc3/pymc-examples/examples/case_studies/blackbox_external_likelihood.html?highlight=author#authors

We could even use https://github.com/sloria/sphinx-issues with the user, pr roles to simplify linking to github users and relevant PRs if using approaches 1 or 3.

[OriolAbril]

I propose to use option 3 with bullet points, like in https://pymc-examples.readthedocs.io/en/latest/survival_analysis/bayes_param_survival_pymc3.html. I think the dates are not necessary but don't hurt either. I propose to use the following categories:

• Alice wrote: for notebooks created specifically for pymc-examples
• Alice adapted Bob's blogpost: for notebooks adapted from blogposts. both authors and blogpost should be links to relevant places
• Alice updated the notebook: basically for everything
• Alice extended the notebook: (we could do without this one) for cases where someone adds new content to the notebook instead of making changes to improve the notebook without changing it's original intent. Updating could be a typo but could also be much more work than extending.
• Alice *re-executed the notebook with PyMC3 x.y.z for rerunning the notebook without changes to code or text.

Main open question that comes to mind is if going forward we want those bullet points to link to the PR with the changes

[tjburch]

@OriolAbril - Links to oriolabril.github.io in your original post all appear broken for me. But going off your explanation, I agree that option 3 is probably the best proposed. But some thoughts:

• If you elect to keep a full log of progressive changes then it should go to the bottom. In your example there, scrolling past 6 bullet points before getting to the example is a bit annoying, and probably the typical person seeking an example doesn't care that much about who reran the notebook, they just want content. (Not to discredit the importance of these things, just the longer it is the more cumbersome it gets)
• That being said, moving all of it to the end motivates the reader to leave before seeing who wrote it. If users never read the authorship, it's not great (if a tree falls in the forest and nobody is there to hear it, does it make a sound?)

If it were me, I'd basically do an amended version of 3 - put a list of contributors at the top:

Authored by john jacob jingleheimer schmidt, contributions from marie curie, albert einstein

Then make the bottom more akin to a changelog with the full description like you propose:

Revision log
Alice wrote: for notebooks created specifically for pymc-examples
Alice adapted Bob's blogpost: for notebooks adapted from blogposts. both authors and blogpost should be links to relevant places
Alice updated the notebook: basically for everything

That way people see contributors, but aren't overwhelmed with too much detail unless they want to look at the bottom.

Last:

Main open question that comes to mind is if going forward we want those bullet points to link to the PR with the changes

I don't see how this would hurt, only help, so I think you should.

[OriolAbril]

I would prefer having a short and synthetic sentence at the top over duplicating info. Duplicating info is much harder to maintain and it quickly ends up containing different info in each place.

We could also try to get that on the left sidebar so it is easily available but doesn't "interfere" with reading the notebook 🤔