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.
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 <lucy.moran.bren...@gmail.com>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 satchmo-users@googlegroups.com. > To unsubscribe from this group, send email to > satchmo-users+unsubscribe@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/satchmo-users?hl=en.
On Mon, Jul 11, 2011 at 3:31 AM, Chris Moffitt <ch...@moffitts.net> 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 < > lucy.moran.bren...@gmail.com> 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 satchmo-users@googlegroups.com. >> To unsubscribe from this group, send email to >> satchmo-users+unsubscribe@googlegroups.com. >> 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 satchmo-users@googlegroups.com. > To unsubscribe from this group, send email to > satchmo-users+unsubscribe@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/satchmo-users?hl=en.
On Wed, Jul 13, 2011 at 1:56 PM, Thomas Rega <tho...@googlemail.com> wrote: > Hi Lucy,
> Am 13.07.2011 um 13:35 schrieb Lucy Brennan:
> > Thanks for the answer.
> > When I have a little more overview, I will submit tickets for the most > concrete problems.
> I would like to help and I am looking forward to these tickets.
> Thomas
> -- > You received this message because you are subscribed to the Google Groups > "Satchmo users" group. > To post to this group, send email to satchmo-users@googlegroups.com. > To unsubscribe from this group, send email to > satchmo-users+unsubscribe@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/satchmo-users?hl=en.
