spacetelescope / dat_pyinthesky

Notebooks for "notebook-driven development" for the Data Analysis Tools efforts
https://dat-pyinthesky.readthedocs.io/en/latest/
8 stars 44 forks source link

Move the developer notes of the notebooks to a uniform syntax #100

Open eteq opened 4 years ago

eteq commented 4 years ago

This plan for development comes from discussion in #84 (e.g. https://github.com/spacetelescope/dat_pyinthesky/pull/84#issuecomment-596774232), #91, and several in-person conversations and a corresponding Jira ticket (not visible in this repo). I'm trying to capture the outcome of that here, but relevant parties are free to add something if I've missed it.

The gist is that we settled on a good approach for including developer notes as individual cells in the notebook that are version controlled along with the notebook. At the outset these will just be visible, but as soon as we get a chance to update the build machinery, we will strip these notes from the built notebook. This has the downside that the downloaded notebooks still have dev notes, but the consensus was that this is really a feature not a bug because we should update the notebooks as dev notes are addressed, and until then it's good for the community to see it as a sort of roadmap of things we know would make their lives easier.

We also settled on a reasonable convention for a developer note that: it should be contained within a single markdown cell (not code cell - code examples in a dev note can be done as literal markdown blocks - i.e. surrounded by```). That cell should begin with the text *Developer Note:*.

So what I see as the remaining to-do’s on this are:

orifox commented 4 years ago

So each of the check boxes above should be a separate tasks? And jira tickets?

eteq commented 4 years ago

So each of the check boxes above should be a separate tasks? And jira tickets?

We could break them out into separate issues in jira to track STScI team work on it, or as separate issues here. But I think they're individually small enough (and best done by one person), so I'm inclined to just say we check them off here as they get done and close this issue once they are.