|
| 1 | +# README File Guidelines and Resources |
| 2 | + |
| 3 | +The **README.md** file is often the first thing that someone sees when they consider |
| 4 | +installing your package. |
| 5 | + |
| 6 | +This file is both the landing page of: |
| 7 | + |
| 8 | +* Your file on package manager landing pages like PyPI and Anaconda |
| 9 | +* Your package's GitHub repository |
| 10 | + |
| 11 | +Thus, it is important that you spend some time up front creating a high quality |
| 12 | +**README.md** file for your Python package. |
| 13 | + |
| 14 | +<!-- # TODO screenshots of landing pages in github and pypi --> |
| 15 | + |
| 16 | +Your README.md file should be located in the root |
| 17 | +of your GitHub repository. |
| 18 | + |
| 19 | +<!-- # TODO provide some screenshots of our repo with a readme file --> |
| 20 | + |
| 21 | +## Organizing your README File from the most broad information to the most specific - Cognitive funneling |
| 22 | + |
| 23 | +We suggest organizing the content in your **README** file so that the most broad information is at the top of the file. Information then |
| 24 | +becomes more specific |
| 25 | +and potentially more technical as the user moves down the file. |
| 26 | + |
| 27 | +```{note} |
| 28 | +[Cognitive funneling approach](https://github.com/hackergrrl/art-of-readme#cognitive-funneling) refers to content structure where the most |
| 29 | +broad information is at the top and becomes increasingly more specific |
| 30 | +and possibly technical lower down in the file. |
| 31 | +``` |
| 32 | + |
| 33 | +This approach of starting broad and progressively getting more specific |
| 34 | +will make your **README** file more accessible and easier-to-digest for a broader group of users. An overly complex or poorly organized **README** |
| 35 | +file will likely result in users getting lost, not understanding |
| 36 | +what your package does and how it could be useful to them. |
| 37 | + |
| 38 | + |
| 39 | +<!-- # TODO make a checklist block style --> |
| 40 | + |
| 41 | +````{note} |
| 42 | +An editor or the editor in chief will ask you to revise your README file |
| 43 | +before a review begins if it does not meet the criteria specified below. |
| 44 | +
|
| 45 | +Please go through this list before submitting your package to pyOpenSci |
| 46 | +
|
| 47 | +``` |
| 48 | +### pyOpenSci README checklist |
| 49 | +
|
| 50 | +Your README file should have the following information: |
| 51 | +- [ ] The name of the package |
| 52 | +- [ ] Badges for the packages current published version, documentation and test suite build. (OPTIONAL: test coverage) |
| 53 | +- [ ] Easy-to-understand explanation (2-4 sentences) of what your tool does |
| 54 | +- [ ] Context for how the tool fits into the broader ecosystem |
| 55 | +- [ ] If it's your package is a wrapper, link to the package that it is wrapping and any associated documentation. (If you do'nt know what a wrapper is - this probably doesn't apply to you!) |
| 56 | +- [ ] A simple quickstart code example that a user can follow to provide a demonstration of what the package can do for them |
| 57 | +- [ ] Links to your packages documentation / website. |
| 58 | +- [ ] A few descriptive links to any tutorials you've created for your pacakge. |
| 59 | +``` |
| 60 | +```` |
| 61 | + |
| 62 | +A more detailed explanation of every element in this check list is below. |
| 63 | + |
| 64 | +## What your README.md file should contain (bare minimum) |
| 65 | + |
| 66 | +At a minimum, your package's **README.md** file should include |
| 67 | +(from top to bottom): |
| 68 | + |
| 69 | +### ✅ Your package's name |
| 70 | +Ideally your GitHub repository's name is also the name of your package. The more |
| 71 | +self explanatory that name is, the better. |
| 72 | + |
| 73 | +### ✅ Badges for current package version, continuous integration and test coverage |
| 74 | + |
| 75 | +Badges are a useful way to draw attention to the quality of your project and to |
| 76 | +assure users that your package is well-designed, tested, and maintained. |
| 77 | +It is common to provide a collection of badges towards the top of your |
| 78 | +README file for others to quickly browse. |
| 79 | + |
| 80 | +Some badges that you should adding to your README file include: |
| 81 | + |
| 82 | +* Current version of the package on pypi / conda forge (the example badge below provides a github release value in our package guide isn't an installable tool.) |
| 83 | + |
| 84 | + |
| 85 | + |
| 86 | + |
| 87 | +```markdown |
| 88 | +Github release |
| 89 | + |
| 90 | +``` |
| 91 | + |
| 92 | +* Continuous integration Status of tests (pass or fail) |
| 93 | + |
| 94 | +Circle CI badge: |
| 95 | +[](https://circleci.com/gh/pyOpenSci/python-package-guide) |
| 96 | + |
| 97 | +Example GitHub actions badge: |
| 98 | + |
| 99 | + |
| 100 | + |
| 101 | +``` |
| 102 | + |
| 103 | +``` |
| 104 | + |
| 105 | +* Citation badge (DOI). It is OK if you do not have a DOI prior to the review. [](https://zenodo.org/badge/latestdoi/556814582) |
| 106 | + |
| 107 | +Once you package is accepted to pyOpenSci, we will provide you with |
| 108 | +a badge to add to your repository that shows that it has been reviewed and accepted into the pyOpenSci scientific Python open source ecosystem! |
| 109 | + |
| 110 | +<!-- # TODO: add a pyopensci accepted badge here --> |
| 111 | + |
| 112 | +```{note} |
| 113 | +Beware of the overuse of badges! There is such a thing as too much of a good thing (which can overload a potential user!). |
| 114 | +``` |
| 115 | + |
| 116 | +### ✅ A short, easy-to-understand description of what your package does |
| 117 | + |
| 118 | +At the top of your README file you should have a short, easy-to-understand, description that details the goals of your package and what purpose it serves. The language in this description should use less technical terms so that a variety of users with varying scientific (and development) backgrounds can understand it. |
| 119 | + |
| 120 | +Consider writing for a 12th grade reading level which is an ideal level for more scientific content that serves a broad user base. The goal of this description to maximize accessibility of your **README** file. |
| 121 | + |
| 122 | + |
| 123 | +### ✅ BRIEF quickstart code demonstration of how to use the package |
| 124 | + |
| 125 | +Include a code quickstart that demonstrates how to use your package. |
| 126 | +This quickstart should be simple. |
| 127 | + |
| 128 | +```{important} |
| 129 | +### TOO MUCH OF A GOOD thing |
| 130 | +
|
| 131 | +Try to avoid including several tutorials in the readme file itself. This too will overwhelm the user with information. |
| 132 | +
|
| 133 | +A short quickstart vignette that shows a user how to use your package is plenty for the README file. All other tutorials and documentation should be presented as descriptive links. |
| 134 | +``` |
| 135 | + |
| 136 | +### ✅ Descriptive links to package documentation, tutorials or vignettes. |
| 137 | + |
| 138 | +Include descriptive links in your README file to: |
| 139 | + |
| 140 | +* The package's documentation page. |
| 141 | +* Tutorials or vignettes that demonstrate application of your package. |
| 142 | + |
| 143 | +### ✅ Discussion of how this package fits within the broader scientific python landscape. |
| 144 | + |
| 145 | +If applicable, describe how the package compares to other similar packages or complementary packages in the scientific Python ecosystem. This discussion can be brief. It's important for package maintainers to consider their package in the context of the broader ecosystem. You will be asked to do this when you submit your package for review for pyOpenSci. |
| 146 | + |
| 147 | +### ✅ Installation instructions |
| 148 | + |
| 149 | +Include instructions for installing your package. If you have published |
| 150 | +the package on both `PyPI` and `Conda` be sure to include instructions for both. |
| 151 | + |
| 152 | +### ✅ Document any addition setup required to use you package |
| 153 | + |
| 154 | +Add any additional setup required that someone will need to do before using your package. Examples of additional setup steps including authentication tokens, or critical dependencies that don't get automatically installed when your package is installed. |
| 155 | + |
| 156 | +### ✅ Citation information |
| 157 | + |
| 158 | +Finally be sure to include instructions on how to cite your package. |
| 159 | + |
| 160 | +### ✅ Links to Contributing Guide, Code of Conduct |
| 161 | +Last but not least provide direct links to your |
| 162 | +**CONTRIBUTING** guide and to your project's **code of conduct**. |
| 163 | + |
| 164 | + |
| 165 | +```{note} |
| 166 | +### README Resources |
| 167 | +
|
| 168 | +Below are some resources on creating great README.md files that you |
| 169 | +might find helpful. |
| 170 | +
|
| 171 | +* [The art of the README GitHub Repo](https://github.com/hackergrrl/art-of-readme) |
| 172 | +* [Write a great readme - Bane Sullivan](https://github.com/banesullivan/README) |
| 173 | +* [Readme resources from rOpenSci](https://devguide.ropensci.org/building.html#readme) |
| 174 | +``` |
| 175 | + |
| 176 | + |
| 177 | +<!-- |
| 178 | +OLD TEXT |
| 179 | +
|
| 180 | +Will ultimately remove this but slowly moving things from difference places |
| 181 | +into the same page. this is all commented out for now. |
| 182 | +
|
| 183 | +### Badges |
| 184 | +
|
| 185 | +Badges are a useful way to draw attention to the quality of your project and to |
| 186 | +assure users that it is well-designed, tested, and maintained. |
| 187 | +It is common to provide a collection of badges in a table for others |
| 188 | +to quickly browse. |
| 189 | +
|
| 190 | +[See this example of a badge table](https://github.com/ropensci/drake). Such a table should be more wide than high. (Note that the badge for pyOpenSci peer-review will be provided upon acceptance.) |
| 191 | +
|
| 192 | +
|
| 193 | +# README.md File Best Practices |
| 194 | +
|
| 195 | +## Adding a Readme file.. Python Package Documentation |
| 196 | +
|
| 197 | +Documentation is as important to the success of your Python open source package |
| 198 | +as the code itself. While quality code is valuable as it gets the tasks that your |
| 199 | +package seeks to achieve, completed, if users don't understand how to use the |
| 200 | +tools in your package then they won't use your tool. |
| 201 | +
|
| 202 | +## Documentation elements that we look for when reviewing a Python package |
| 203 | +
|
| 204 | +In the pyOpenSci peer review process we look for several things when evaluating |
| 205 | +package documentation including: |
| 206 | +
|
| 207 | +1. A clear and to the point README file |
| 208 | +2. Documentation of the funcaintliy of your code. This is often setup using Sphinx/ Read the docs or some other documentation platform |
| 209 | +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) |
| 210 | + --> |
| 211 | + |
0 commit comments