Packaging guide updates

code-style-structure/intro.md

@@ -1,4 +1,6 @@
-# Code style and structure
+# DELETE ME Code style and structure
 
 
-Under development
+Under development - possibly remove this as it's in the package structure 
+and might 
+make sense there. 

documentation/contributing.md

@@ -1,27 +1,47 @@
-# CONTRIBUTING file and License
+# Contributing and License Files in your Python Package
 
-## CONTRIBUTING.md File for your Python Package 
+Your python package should include a file called **CONTRIBUTING.md** located in the 
+root of your repository (with your **README.md** file).
 
-Your python package should include a file called CONTRIBUTING.md located in the 
-root of your repository (with your readme file).
+## What should be in the contributing guide
 
-### Local development environment information 
+The contributing file should include information about the types 
+of contributions that you welcome, and how you'd like to see 
+contributions happen. 
 
-The contributing file should include information to support a new contributing 
-building your package locally. This includes:
-
-* instructions for setting up a development environment locally to work on your package
-* instructions for how the test suite is setup and run 
-
-### Community contribution guidelines
 This guide should also include information for someone interested in asking questions, 
 submitting issues or pull requests:
 
 * Any guidelines that you have in place for users submitting issues, pull requests or asking questions. 
 * A link to your code of conduct
 * A link to or include how your code of conduct is enforced.
 
-```{note}
+It should also include informative descriptive links for a 
+development guide (see below) that has instructions for:
+
+* Setting up a development environment locally to work on your package
+* How the test suite is setup and run 
+* How you can build docs locally
+
+## Development guide for your package 
+
+
+
+### Why a development guide is important 
+
+While a well thought-out continuous integration setup in your repository 
+can allow users to skip building the package locally (especially if they are just updating text), it's valuable to have a development guide, in the case that you wish to:
+
+* onboard new maintainers
+* allow technically inclined contributors to make thoughtful code based pr's
+
+It also is important to pyOpenSci that the maintenance workflow is 
+documented in the case that we need to help you onboard new 
+maintainers in the future. 
+
+
+
+```{tip}
 [The mozilla open workshop has a nice outline of things to consider when 
 creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/)
 ```

documentation/index.md

@@ -6,20 +6,23 @@
 ## Documentation is critical to the success of your Python open source package 
 
 Documentation is as important to the success of your Python open source package 
-as the code itself. While quality code is valuable as it gets the tasks that your
-package seeks to achieve, completed, if users don't understand how to use the 
-tools in your package then they won't use your tool. 
+as the code itself. Quality code is of course valuable as it gets the tasks 
+that your package seeks to achieve, done. However, if users don't understand 
+how to use the tools in your package, then they won't use your tool. 
+
+Further, if you wish to build a base of contributors to your package, having 
+explicit information about how to contribute is critical.
 
 ## Documentation elements that we look for when reviewing a Python package
 
 In the pyOpenSci peer review process we look for several things when evaluating
 package documentation including:
 
-1. A clear and to the point **README.md** file 
-2. Documentation of the functionality of your code. This is often setup using Sphinx/ Read the docs or some other documentation platform 
-3. Sufficient API documentation of your packages API (this means that docstrings are formatted with explanations of each variable and better yet quick vignettes that demonstrate how to use the function or class). If you don't know what API documentation means this section is FOR YOU! 
-4. A **CONTRIBUTING.md** file that has clear instructions that others can follow to setup a development environment. This will support others contributing to your project. 
-5. A license file that helps people 
+1. [A clear and to the point **README.md** file](readme-files)
+2. **Clear package documentation** that helps users understand how to install, use and cite your package. Package documentation is often setup using [Sphinx](https://www.sphinx-doc.org/en/master/) which is a Python-focused documentation engine. You can host your documentation using github pages or an online tool like [readthedocs](https://www.readthedocs.org).
+3. **Package API documentation.** Package API documentation refers to documentation for each class, function, method and attribute that is user facing in your package. This mean means that your package methods and classes have docstrings that are formatted with explanations of each variable and better yet quick vignettes that demonstrate how to use the function or class). If you don't know what API documentation means this section is for you! 
+4. A **CONTRIBUTING.md** file that outlines how others can contribute to your package. This file should also link to your development guide and code of conduct.A well-crafted contributing guide will make it much easier for the community to contribute to your project. 
+5. A license file. 
 
 <!-- # TODO LINK TO CI BUILD examples FOR Documentation - we have plenty in our repos already for folks to look at. -->