Description
I'm a huge fan of the docs over at cookiecutter-pypackage. They are clean, precise and have a great structure.
I'd like to clean up the docs for Cookiecutter Django and structure them in a similar way. That'd make it easier to get from zero knowledge to a working local environment with a production deployment and will hopefully reduce doc related issues.
What I have in mind is a structure with 4 major categories Setup, The Project, Local Development and Production each with their own precise steps, a FAQ and troubleshooting section.
Setup
Steps taken to create a Cookiecutter Django project
- Step 0: Install Python (links on how to do this on multiple platforms)
- Step 1: Install Cookiecutter
- Step 2: run cookiecutter against Cookiecutter Django
- Step 3: Create Github Account & Repo
- ..
- ..
- FAQ
- Troubleshooting
The Project
Everything about the project in general
- Structural overview
- Features
- Settings
- ...
- Dependencies
- FAQ
- Troubleshooting
Local Development
Docker
From nothing to a working development environment with Docker
- Step 1: Install Docker for Mac
- ...
- ...
- FAQ
- Troubleshooting
Vanilla Python
From vanilla Python to a working development environment
- Step 1: Setup a venv
- ....
- Step X: Postgres on macOS, Windows, Linux
- FAQ
- Troubleshooting
Production
Prerequisites
Everything we need prior to deploying to prod which are platform agnostic
- Step 1: Register Domain
- Step 2: Setup Mail
- Step 3: Setup AWS credentials
- ...
- ...
- FAQ
- Troubleshooting
Docker
From a fresh linux install to a working Docker deployment
- Step 1: Install Docker & Docker Compose
- ...
- FAQ
- Troubleshooting
Ubuntu
From a fresh Ubuntu install to a app
- Step 1: Use the bootstrap Script
- Setup Postgres
- ...
- FAQ
- Troubleshooting
Heroku
make clear that this may not be fully supported
Python Anywhere
make clear that this may not be fully supported
This will be a lot of work, but I think it's worth it in the long run. I think the best way to approach this would be if I restructure the docs first, filling each step from the "old" docs and see where we go from there.
Once we have this in place, we'd need people testing them out, report errors and possibly fill in gaps and work on the corresponding FAQ and troubleshooting section.
Who is willing to help here? We need everyone, really. From zero knowledge to a full stack expert running hundreds of Cookiecutters in prod.