fix: update to contributing and links

Author: lwasser

documentation/repository-files/code-of-conduct-file.md

@@ -1,3 +1,5 @@
+(coc-file)=
+
 # The CODE_OF_CONDUCT file - Python Packaging
 
 ```{admonition} Example CODE_OF_CONDUCT files

documentation/repository-files/contributing-file.md

@@ -1,25 +1,65 @@
-# Contributing File in your Python Open Source Package
+(contributing-file)=
+
+# Your Python Package CONTRIBUTING File
+
+The **CONTRIBUTING.md** is the landing page guide for your project's contributors. It outlines how contributors can get involved, the contribution types that you welcome, and how contributors should interact or engage with you and your maintainer team. The contributor guide should also link to get-started resources that overview how to set up development environments, what type of workflow you expect on GitHub/GitLab, and anything else that contributors might need to get started.
+
+This file benefits maintainers and contributors. For contributors, it provides a roadmap to getting started making their first contribution easier. For maintainers, it answers commonly asked questions and reduces the burden of explaining your process to every person who wants to contribute. This document creates a more collaborative and efficient development process for everyone.
+
+## CONTRIBUTING files lower barriers to entry
+
+The contributing file lowers barriers to entry for new and seasoned contributors as it provides a roadmap.
+
+- **For Contributors**: It provides clear instructions on contributing, from reporting issues to submitting pull requests.
+- **For Maintainers**: It streamlines contributions by setting expectations and standardizing processes, reducing the time spent clarifying common questions or handling incomplete issues or pull requests.
+
+Including a well-written CONTRIBUTING.md file in your project is one way of making it more welcoming and open to new and seasoned contributors. It also helps create a smoother workflow for everyone involved.
+
+## Make it welcoming
+
+Make the guide welcoming. Use accessible language to encourage participation from contributors of all experience levels. For example:
+
+- Avoid technical jargon or explain terms when necessary (e.g., "fork the repository").
+- Include a friendly introduction, such as "Thank you for your interest in contributing! We're excited to collaborate with you."
+- Highlight that all contributions, no matter how small, are valued.
 
 ## What a CONTRIBUTING.md file should contain
 
-```{admonition} Example contributing files
+:::{admonition} Example contributing files
 :class: tip
 
-* [pyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)
-* [fatiando verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md)
-```
+- [pyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md)
+- [fatiando verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md)
+:::
+
+Your Python package should include a file called **CONTRIBUTING.md** located in the
+root of your repository next to [your **README.md** file](readme-file).
+
+The CONTRIBUTING.md file should include information about:
+
+- The types of contributions that you welcome
+
+> Example: We welcome contributions of all kinds. If you want to address an existing issue, check out our issues in this repository and comment on the one that you'd like to open to. Otherwise, you can open a new issue...
 
-Your Python open source package should include a file called **CONTRIBUTING.md** located in the
-root of your repository (with your **README.md** file).
+- How you'd like contributions to happen. Clearly outline your contribution process. For example:
+  - Should contributors address open issues
+  - Are new issues welcome?
+  - Should contributors open a pull request (PR) directly or discuss changes first?
 
-The contributing file should include information about the types
-of contributions that you welcome, and how you'd like to see
-contributions happen.
+- Include instructions for the fork and pull request workflow, and link to resources or guides explaining these steps (if available).
+- Guidelines that you have in place for users submitting issues, pull requests or asking questions.
+
+If you have a [development guide](development-guide), link to it. This guide should provide clear instructions on how to set up your development environment locally. It also should overview and CI tools that you have that could simplify the contribution process (e.g. pre-commit.ci bot, etc), linters, code formatters, etc.
 
 This guide should also include information for someone
-interested in asking questions, submitting issues or pull requests. It should have things like:
+interested in asking questions. Some projects accept questions as GitHub or GitLab issues. Others use GitHub discussions, Discourse or even a discord server.
+
+The contributing file should also include:
+
+- A link to your [code of conduct](coc-file)
+- A link to your project's [LICENSE](license-file)
+- A link to a [development guide](development-guide) if you have one
+
+## Summary
 
-* 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 licensing information found in your README file.
-* A link to a development guide if you have one
+A well-crafted CONTRIBUTING.md file is welcome mat for your project! By providing clear instructions, helpful resources, and a welcoming tone, you make it easier for contributors to get involved and build a stronger, more collaborative community around your project.

documentation/repository-files/development-guide.md

@@ -1,3 +1,5 @@
+(development-guide)=
+
 # What the development guide for your Python package should contain
 
 Ideally, your package should also have a development guide. This file may live in your package documentation and should be linked to from your CONTRIBUTING.md file (discussed above).
@@ -9,6 +11,7 @@ technically proficient users how to:
 * Build documentation locally
 
 The development guide should also have guidelines for:
+
 * code standards including docstring style, code format and any specific code approaches that the package follows.
 
 It's also helpful to specify the types of tests you request if a contributor submits a new feature or a change to an existing feature that will not be covered by your existing test suite.
@@ -38,14 +41,11 @@ pyOpenSci requires a package to have in order to be eligible for
 review. Some maintainers may also opt to include the development information in their contributing guide.
 ```
 
-
 ```{tip}
 [The Mozilla Science Lab website has a nice outline of things to consider when
 creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/)
 ```
 
-
-
 <!--
 pyOpenSci packages must:
 

documentation/repository-files/license-files.md

@@ -3,9 +3,11 @@ bibliography:
   - ../../bibliography.bib
 ---
 
+(license-file)=
+
 # License files for scientific Python open source software
 
-:::{button-link} https://www.pyopensci.org/about-peer-review/
+:::{button-link} <https://www.pyopensci.org/about-peer-review/>
 :color: primary
 :class: sd-rounded-pill float-left
 
@@ -30,7 +32,6 @@ and more.
 
 [Read more about why license files are critical in protecting both you as a maintainer and your users of your scientific Python open source package.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)
 
-
 ## Where to store your license
 
 Your `LICENSE` file should be stored at root of your GitHub / GitLab repository.
@@ -60,7 +61,7 @@ Free and open source software is intrinsically political, and it is important to
 ### How to choose a license
 
 To select your license, we suggest that you use GitHub's
-[Choose a License tool ](https://choosealicense.com/).
+[Choose a License tool](https://choosealicense.com/).
 
 If you choose your license when creating a new GitHub repository, you can also
 automatically get a text copy of the license file to add to your repository. However
@@ -114,7 +115,6 @@ They have fewer **inbound** restrictions - a GPL-3 licensed package can include
 |            <i class="fa-solid fa-x" style="color: Crimson"></i> |                             | Copyleft     | Permissive                           |
 | <i class="fa-solid fa-check" style="color: MediumSeaGreen"></i> |                             | Copyleft     | Copyleft                             |
 
-
 :::{admonition} An example of how a license determine how code can be reused
 :class: note
 
@@ -128,16 +128,14 @@ This would not be true with a GPL licensed package. `GPL-3` packages can include
 🚨 Proceed with caution! 🚨
 :::
 
-
-##  What about software citation?
+## What about software citation?
 
 While many permissive licenses do not require citation we STRONG encourage that you cite all software that you use in papers, blogs and other publications. You tell your users how to cite your package by using a [citation.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files). We will cover this topic when we talk about creating DOI's for your package using zenodo.
 
 <!-- TODO: add link when lesson is created - but also we don't yet know how citation.cff files work with Zenodo (do they work??) will the citation info update with a new Zenodo link
 
 These files - we need to understand if that date releases auto populates or forces zenodo to modify it's citation. If it's not dynamic it could be problematic
 
-
 -->
 
 # References

documentation/repository-files/readme-file-best-practices.md

@@ -1,3 +1,5 @@
+(readme-file)=
+
 # README File Guidelines and Resources
 
 Your **README.md** file should be located in the root of your GitHub repository.
@@ -11,8 +13,8 @@ The README.md file is the landing page of:
 
 Your README.md file is also used as a measure of package and community
 health on sites such as:
-* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/anitagraser/movingpandas/community) and [Snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas)
 
+* [GitHub community health for MovingPandas (available for all repositories)](https://github.com/anitagraser/movingpandas/community) and [Snyk - moving pandas example](https://snyk.io/advisor/python/movingpandas)
 
 ```{figure} /images/pandera-python-package-readme-github.png
 ---
@@ -52,10 +54,11 @@ Your README file should have the following information:
 Your **README.md** file should contain the following things (listed from top to bottom):
 
 ### ✔️ Your package's name
+
 Ideally your GitHub repository's name is also the name of your package. The more
 self explanatory that name is, the better.
 
-###  ✔️ Badges for current package version, continuous integration and test coverage
+### ✔️ Badges for current package version, continuous integration and test coverage
 
 Badges are a useful way to draw attention to the quality of your project. Badges
 assure users that your package is well-designed, tested, and maintained. They
@@ -85,7 +88,6 @@ a badge to add to your repository that shows that it has been reviewed.
 
 ```
 
-
 ```{caution}
 Beware of the overuse of badges! There is such a thing as too much of a good thing (which can overload a potential user!).
 ```