The README.md of a GitHub repo is like a welcome mat: It's the first thing you see when you arrive on a project's doorstep.
The easier you can make it for users or other developers to glean important information about your project, the better.
Here are some great examples of README.md files:
Many of these README.md files include a series of badges at the top.
These badges are not only visual indicators of certain information---whether the repo is in a healthy state with passing tests, which channels are available for obtain the tool, which version number is current, and how many times the software has been downloaded---they provide quick links to a variety of useful integrated services.
Some useful badges:
- Travis badge
- AppVeyor badge
- pypi version and downloads badges
- Anaconda Cloud version and download badge
- Depsy badge
- Zenodo DOI badge
There are many tools that can be used to write documentation. The easiest to start with is the GitHub wiki, which uses markdown syntax just like the rest of GitHub.
If you're already hosting your project on GitHub, perhaps the easiest to start with is Github wiki which uses the same GitHub markdown syntax. GitHub wikis are version controlled, and can even be edited like a standard Git repository.
Helpful guide on GitHub wikis: https://guides.github.com/features/wikis/
Some good examples of wiki-based documentation:
If you need something slightly more powerful, consider using Sphinx, which has excellent support for producing beautiful Python documentation. From the same documentation source, you can build both HTML (online) and PDF (offline) versions, among many others supported.
Hosting a sphinx project can be tricky on its own, but is almost trivial if you have a public GitHub repository, since you can use Read the Docs (RTD), which automatically rebuilds and hosts the documentation every time you commit to your repository. This template and this tutorial can help you easily get started.
If you're using conda for your code, you may want to check out this step by step guide on setting up a conda project with RTD.
Some good examples of Sphinx documentation:
- Sphinx docs, hosted on Read the Docs: protons | ensembler
- Sphinx docs, built by travis and hosted on S3: openmm | mdtraj | pymbar | yank | pymc
- readme.io: A collaborative system for writing documentation
- GitBook: An online collaborative publishing toolchain
Almost nobody reads the complete user documentation for a tool before jumping in. Attention spans are limited; if it takes more than a few minutes to figure out how to accomplish the desired action with a new code---especially if that action is perceived as common---it's likely the user will give up and try a different approach.
Many users---yourself included---find the easiest way to get started with a new code is to try out a working example similar to the task of interest and then tweak things from there. Clear, simple, working examples are the quickest way to get someone using your code.
Good examples of good examples:
- mdtraj has a great page of examples to help users dive right in.
- MDAnalysis starts with a great simple example to illustrate how easy it is to use.
Documenting what has changed with each revision or release of your code is an important part of recording when new features were added, existing features were changed, or when critical bugs were fixed.
autoprotocol has a great example of good changelog documentation using RTD
Want to contribute to this repository? Have a suggestion for an improvement? Spot a typo? We're always looking to improve this document for the betterment of all.
- Please feel free to open a new issue with your feedback and suggestions!
- Or make a pull request from your branch or fork!
| Previous: | Next: | |
|---|---|---|
| Continuous Integration | Back to Top | Python Optimization |