- What’s a README?
- Modern day added formatting. Mostly Markdown, sometimes Restructured Text.
- What to include in a README?
- Name the project
- Intro / Summary / Overview
- Installation instructions
- Usage instructions
- Contribution instructions.
- Credit for important contributors.
- Acknowledgments of projects you based yours on.
- Ways to communicate with you or the community.
- License information.
- Project status information in the form of badges.
In my early days with Python, one of the things that I really liked was using the built-in
help function to examine classes and methods while sitting at the interpreter, trying to determine what to type next. This function imports an object and walks through its members, pulling out docstrings and generating manpage-like output to help give you an idea of how to use the object it was examining.
The beauty about it being built into the standard library is that with output being generated straight from code, it indirectly emphasizes a coding style for lazy people like me, who want to do as little extra work as possible to maintain documentation. Especially if you already choose straight forward names for your variables and functions. This style involves things like adding docstrings to your functions and classes, as well as properly identifying private and protected members by prefixing them with underscores.Continue reading