This is a brief one, I hope.
I wanted to save time so I learnt Django. Then I wanted to save more time building a CMS and a blog so I learnt Wagtail. Then I wanted to save even more time so I learnt Puput. The problem was, as I went from Django to Wagtail to Puput, the documentation got thinner and thinner and thinner. And more and more and more abstract. Not ideal for beginners, at all.
Wagtail “Post date” Problem
I followed the Wagtail introductory tutorial strictly, but when I used “date = models.DateField(“Post date”)” like in the tutorial, I kept getting: “django.core.exceptions.ValidationError: [“‘Post date’ value has an invalid date format. It must be in YYYY-MM-DD format.”]”.
After googling for a full day, I got fed up and visited the Wagtail channel on IRC Freenode where someone said to run “manage.py migrate blog zero”, remove all files in the migrations folder except for __init__.py and then run makemigrations and migrate again to start from scratch. That meant all my test posts were gone but it fixed the problem.
Nobody knew exactly what went wrong. I suspect it’s because when we follow tutorials and test things out in different ways we might create conflicts in the database. I don’t know. Just guessing.
Puput Installation Problem
The bigger problem arrived when I tried to integrate Puput into my Wagtail project. The documentation does tell you how to do it, except that it throws up a few errors irresolvable by beginners. Since I didn’t have a full blown blog I had to integrate, I was comfortable dumping my test Wagtail blog entirely and building the Puput one from scratch.
The Puput setup documentation says you have to do different things depending on whether you’re installing Puput on top of Wagtail or on top of Django. I’ve found neither to work when strictly followed. Instead, what worked was when I followed the setup instructions for integrating Puput into a Django project minus the part where you add PUPUT_APPS into INSTALLED_APPS.
Once I left it out, I could migrate without error code 1 and other errors showing up. Then I could build the blog up from scratch.
I solved a handful of other problems by following the code. If the tutorial said to do something but it didn’t work, I would go into the Puput package, weasel out the module I’m supposed to be referencing, find the appropriate code in it, and try to understand what exactly it does. This was harder than I thought, since half of it didn’t make sense to me. The other half did though, thankfully.
Wagtail works slightly differently from Django, and Puput is almost entirely different structurally. They’re not difficult to understand. It just takes a lot of time, googling, and asking around, and thank goodness for IRC, amirite?
I thought using open source packages would save me time, and perhaps it will in the long run. I do really like Puput and Wagtail and Django. But it can be really hard on beginners, especially when some of us have to work to pay the rent and we’re stealing literally ten bare minutes off the end of the day to learn this stuff with bleary eyes and tired minds.
Clear documentation and tutorials are so important. I hope I get some free time and energy to write up clearer ones for Puput soon.