Um outro exemplo de uma documentação que podia ser bem melhor é a biblioteca South. Raciocinem comigo: 99% das pessoas que vão começar a usá-la já tem um banco funcionando e sentem necessidade de utilizar o south para automatizar suas atualizações, concordam? Ou seja, quase ninguém que está começando a aprender a usar Django já vai de cara usar o south, concordam ?
Entretanto, a documentação do south parte do principio que você vai começar a usar de uma base vazia e não dá um passo a passo explícito de como fazer uma instalação em uma base já "populada". Até tem uma página especial explicando como usar uma base existente. Mas essa tinha que ser a primeira página, concordam??! Ou seja, cabeça de desenvolvedor :)
Assim, segue um pequeno tutorial para quem já tem uma base existente e quer utilizar o south sem susto:
1) Instalação:
sudo easy_install south
2) Teste se a instalação foi bem sucedida realmente:
python manage.py shell
> import south
3) Entre no seu projeto e edite o settings.py, incluindo na lista INSTALLED_APPs, a string o 'south'
4) Crie a estrutura de dados do próprio south com
python manage.py syncdb
5) Aqui está o pulo do gato:
python manage.py schemamigration aplicacao --initial
python manage.py migrate aplicacao 0001_initial --fake
6) Agora faça um teste simples, altere um modelo qualquer adicionando um campo booleano, por exemplo e veja a mágica do south funcionando:
python manage.py schemamigration aplicacao --auto
python manage.py migrate aplicacao
Este pequeno tutorial teve a valiosa colaboração e suporte do pessoal do Alatazan.
Ainda sobre documentação. Tem uma ótima exceção que vale a pena comentar: fiquei tão impressionado com a documentação e qualidade do django-admin-tools que fiz uma contribuição em dinheiro para o desenvolvedor. Como eu sempre digo, elogio é bom mas com dinheiro no bolso, ele fica mais sincero...