Thanks for the answer. When I have a little more overview, I will submit tickets for the most concrete problems.
Lucy On Mon, Jul 11, 2011 at 3:31 AM, Chris Moffitt <[email protected]> wrote: > Lucy, > > I don't disagree that the documentation could be improved. I've admitted > this in the past and suggested that I'm open to improvements. All of the > docs are in bitbucket so if people are interested, they can clone and issue > pull requests. I don't even mind if people submit tickets with detailed > suggestions or requests. I'm open to putting time into the docs but I'm > somewhat too close to know if what I'm doing is actually useful to people. > > Thanks, > Chris > > On Sat, Jul 9, 2011 at 12:30 PM, Lucy Brennan < > [email protected]> wrote: > >> 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 >> documentation. >> >> 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 >> problems. >> >> 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 >> >> -- >> >> You received this message because you are subscribed to the Google Groups >> "Satchmo users" group. >> To post to this group, send email to [email protected]. >> To unsubscribe from this group, send email to >> [email protected]. >> For more options, visit this group at >> http://groups.google.com/group/satchmo-users?hl=en. >> >> > -- > You received this message because you are subscribed to the Google Groups > "Satchmo users" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]. > For more options, visit this group at > http://groups.google.com/group/satchmo-users?hl=en. > -- You received this message because you are subscribed to the Google Groups "Satchmo users" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/satchmo-users?hl=en.
