Improve tiered shipping docs

Issue #1107 wontfix
John-Scott Atlakson
created an issue

In http://bitbucket.org/chris1610/satchmo/changeset/f9d87d901942/ the dotted module name was removed from the section on tiered shipping. Please add back the reference to shipping.modules.tiered so users know what they should add to INSTALLED_APPS.

Additionally, the documentation only says 'what' you can do with this module but it does not say 'how'. What is a carrier key? What should be entered here? Documenting the required fields and providing a concrete example would be very helpful.

Comments (5)

  1. Tay Ray Chuan

    Hi,

    that changeset attempted to "refactor" instructions for enabling modules - specifically, those with Django-style models. We also do this for modules with no models in ea46937a6263 .

    This is so that we don't have to keep repeating ourselves when telling the users how to enable, say, custom shipping modules, and tiered shipping. I believe the user is sufficiently fluent in python/django to know what "dotted module name" to use when modifying INSTALLED_APPS.

    Regarding the lack of details in doc: you're welcome to fork and contribute to them.

  2. Anonymous

    I'm glad you had second-thoughts! Seriously, high fives!

    I totally get refactoring, eliminating duplication etc. I'm a developer too. But nothing about knowing Python/Django would make me magically know that the module is `shipping.modules.tiered` when the #1 Google result for "satchmo enabling tiered shipping" returns an official slideshow at scribd and Google's snippet shows the completely outdated `satchmo.shipping.modules.tiered`. I had to dig through my virtualenv's src to figure out what the correct import path would be. And for the hg checkout I'm using (not tip) I had to add it to both INSTALLED_APPS and as a CUSTOM_SHIPPING_MODULES to at least get runserver working without errors. Time better spent elsewhere. Even after that I couldn't get it working because I have no idea how enabling this interacts with existing shipping modules.

    In regards to my other comments about providing concrete examples of what the required fields 'mean' and how they are used...my friend, it's anyone's guess! I don't have time to read through this tangled web of code to try to figure out what the implications are. Really, what does Carrier.key do? Why is it required? Where else is it used? The regular docs cover absolutely nothing. I haven't the faintest idea about this field and yet I must supply a value! Do I have to add a CarrierTranslation? What goes in these fields and why?

    There is no description of how to use the functionality, just a not entirely helpful "you could use it for x, y and z if only you knew what we were thinking in our heads when we wrote the code." The code itself is undocumented (not even so much as help_text on the model fields). I realize it's all volunteer work and I realize that you personally have not been responsible for much of the code. I do appreciate your efforts to improve the documentation, they are getting better and have really needed some serious work. Django really sets the bar high on quality documentation but I think it's crucial to strive for their standard.

    Anyway, thanks for your updates. Please consider my other remarks. If you have the ear of the core developers, it could be a very simple job ("what should the help_text be on these fields for a non-programmer using the admin?"). This would go a long way to simplifying adoption by other developers working under deadlines.

  3. Log in to comment