Satchmo documentation not in it's best shape

[Lucy Brennan]

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

[Chris Moffitt]

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

--
You received this message because you are subscribed to the Google Groups "Satchmo users" group.
To post to this group, send email to satchm...@googlegroups.com.
To unsubscribe from this group, send email to satchmo-user...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/satchmo-users?hl=en.

[Lucy Brennan]

Thanks for the answer.

When I have a little more overview, I will submit tickets for the most concrete problems.

Lucy

[Thomas Rega]

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

[Lucy Brennan]

Hi again.

Thanks Thomas.

Now I have committed three tickets, of which two are on documentation.

They are each not targeted on a specific article in the documentation, but more on a concept.

Sincerely, Lucy

--