Pinax 18.01 Standardizing READMEs

Standardizing READMEs

I've had a request to direct others to a standard format for Pinax repos docs. I've previously looked through the Pinax repos to get a sense of what info there is, what would be relevant to include, what is duplicate info, or would be better covered in the main docs.

Markup

We use Github-flavored MarkDown. The read-me file is always named "README.md".

Proposed Format

• Patch (if exists)
• App Title (i.e. "Pinax Webanalytics")
• Badges
• Table of Contents
• About Pinax (short blurb)
• App Name (i.e. "pinax-webanalytics")
• Overview
  • Features (if, applicable)
  • Supported Django and Python Versions
• Documentation (headings vary by app)
  • Installation
  • Getting Started
  • Usage
• Change Log
• History (if, applicable)
• Contribute
• Code of Conduct
• Connect with Pinax
• License

Include If Applicable

• Backwards Incompatible Changes
• FAQs
• App Demo

Remove or Duplicate (these are various sections found in Pinax repos that seem to be duplicate or perhaps should be covered in main docs?)

• Pinax
• Reference Guide
• Environment Setup
• Quickstart
• Dependencies
• Additional
• Getting Started and Documentation
• Setting up Documentation
• Upgrade Notes (same as Change Log?)
• Running the Tests (main docs?)
• Contributors (under authors only?)
• Pinax Project Blog and Twitter (More Info section?)
• License & Attribution (remove?)