feb 28 notes

Author: hackmd-deploy

meeting-notes/2020-02-28-notes.md

@@ -0,0 +1,93 @@
+---
+tags: pyopensci, python
+---
+
+# pyOpenSci Meeting Notes - 28 Feb 2020
+
+
+## Attendees
+
+* Leah Wasser, Earth Lab, CU Boulder
+* Jenny Palomino, Earth Lab, CU Boulder
+* Chris Holdgraf, UC Berkeley
+* Ivan Ogasawara, Quansight
+
+## Discussion Points
+
+### How Much Documentation is "Good Enough" for PyOpenSci?
+
+* How much documentation is enough: dev_guide says "all user facing functions should have documentation with examples"
+
+What is our good enough requirement for documentation
+
+1. docstrings: do ALL docstrings needs examples even if there is a solid help / gallery.
+
+Current language in our dev guide:
+
+* MINIMUM: Some examples of how to use the functions
+* Better: Docstring generated 
+
+ * Chris will email alison hill (r studio ) who gave a good talk on docs. 
+ * Create a little survey on what people expect for documentation?
+
+JOSS REQUIREMENTS
+
+https://joss.readthedocs.io/en/latest/review_criteria.html#example-usage
+
+Maybe we switch to ok, better, best
+
+### Documentation
+
+New language below:
+
+**ok (required)**: all user facing functions (inputs and outputs) are documented both in the code and in the user-facing documentation.
+**better**: all user facing functions are documented with examples (in tutorials or doc strings)
+**best**: all user facing functions are documented and there is are tutorials (vignettes) that demonstrate example user workflows 
+
+
+
+```
+README 
+All packages should have a README.md in their root directory. The README should include, from top to bottom:
+
+The package name
+Badges for continuous integration and test coverage, the badge for pyOpenSci peer-review once it has started (see below), a repostatus.org badge, and any other badges. If the README has many more badges, you might want to consider using a table for badges, see this example, that one and that one. Such a table shoud be more wide than high.
+Short description of goals of package, with descriptive links to all vignettes (rendered, i.e. readable, cf the documentation website section) unless the package is small and there’s only one vignette repeating the README.
+Installation instructions
+Any additional setup required (authentication tokens, etc)
+Brief demonstration usage
+Direction to more detailed documentation (e.g. your documentation files or website).
+If applicable, how the package compares to other similar packages and/or how it relates to other packages
+Citation information
+Good/Better/Best Recommendations:
+
+Good: README with name, description, installation instructions, and direction to further documentation.
+Better/Best: All the above plus usage examples, citation information, and CI and/or test coverage badges.
+
+
+Documentation 
+All external package functions, classes, and methods should be fully documented with examples.
+
+Good/Better/Best:
+
+Good: Manually updated documentation as text files that ship with your package.
+Better: A documentation website using Sphinx to convert rst files to HTML and Read the Docs to host your site.
+Best (optional): Also consider automatically generated documentation from docstrings using autodoc
+```
+
+  * https://www.pyopensci.org/dev_guide/packaging/packaging_guide#Documentation
+  * [Example review comment](https://github.com/pyOpenSci/software-review/issues/16#issuecomment-586647024)
+  * [Discourse discussion on Good, Better, Best](https://pyopensci.discourse.group/t/good-better-best-required-versus-recommended-changes-by-reviewers-your-feedback-is-requested/160)
+
+### Reviews
+one created a google doc. i can see why this is useful but i may need to copy some of it into the issue just in case that doc ever disappears. in the future as the editor i should make sure that the text is in the issue itself. 
+
+### Similarly, Testing - What if Tests Are Failing?
+
+* maybe this is a space for community feedback as well? what if tests fail? How much do we want to enforce test integrity?
+* expected to fail tests 
+
+
+### Meeting time
+
+Earlier is better in the day.