I have been through the Django documentation, which was surprisingly
well written and well structured. At first glance the Satchmo
documentation seems similar with a Quick start guide, and from then
on, several well defined articles going deeper and deeper. I have a
feeling that Satchmo was/is inspired by and aspiring to the Django
However, I have had a lot of problems with the Satchmo documentation.
And because Satchmo is such a big framework, documentation is in
opinion very important.
The main problems that I see:
1) Information is outdated. E.g. the documentation sometimes refer to
variables that do no longer exist in the code.
2) Examples do not work. Even the clonesatchmo.py example has
3) Articles finish too soon. They are simply not going deep enough.
4) There is little or no reflection in the articles. Why is approach
so smart, why even use this instead of that. Pros and cons.
5) No mention of the pitfalls in whatever an article describes.
6) No option for readers to comment on articles. If that was possible
many pitfalls, typos, extra insight, helpful notes, etc. could be
shared with other readers.
With sincerity, Lucy Brennan