Documentation for Commerce Promotions Intro#272
Documentation for Commerce Promotions Intro#272stephanieg467 wants to merge 2 commits intodrupalcommerce:masterfrom
Conversation
| ------------ | ||
|
|
||
| The competitive nature of the current retail market has driven store owners to search for methods and strategies | ||
| to stand out from the competition and to drive sales. Creating promotions has been the strategy that has proven most effective |
There was a problem hiding this comment.
Is there a standard line length in other pages? It's odd to see lines to be such different lengths. You might want to wrap as close to 80 characters as possible without going over (like Drupal coding standards for comments) or whatever other commerce docs pages do.
| to stand out from the competition and to drive sales. Creating promotions has been the strategy that has proven most effective | ||
| for achieving those two goals. Commerce Promotions in Commerce 2.x provides the site administrator with the tools necessary to | ||
| turn their innovative promotion ideas into reality. | ||
| How exactly does Commerce Promotions achieve this you ask? Commerce Promotions works with [Commerce Orders] (../07.orders) |
There was a problem hiding this comment.
Do you mean "work with" instead of "works with"?
| * usage_limit [integer] - [DEFAULT = 0] | ||
| * The maximum number of times the promotion can be used. 0 for unlimited. | ||
| * | ||
| * start_date [datetime] - [datetime_type = date] [DEFAULT = current date] |
There was a problem hiding this comment.
I wonder how specific we want to get here. This details could be rendered obsolete really easily. For example, https://www.drupal.org/project/commerce/issues/2977618 is changing the dates to datetime instead of just date. If we leave this more open, such as just describing what start and end date are for rather than the specific implementation, there'll be less of a burden to keep this up to date. Those details may be just as easy to look at the code to find out instead.
I'm worried that these docs would need too much maintenance done in tandem with work in the drupal.org issues (or worse, with module releases, since people probably expect these docs to match the current stable release, not the latest dev version). It'd be no fun for someone to read one thing here and find out it's changed in the code.
lisastreeter
left a comment
lisastreeter
left a comment
There was a problem hiding this comment.
There's a lot of great information in here, and I think it could be effectively broken up into multiple pages so that it's easier to digest. I suggest:
-
For the user/pages/03.commerce2/02.developer-guide/09.promotions/docs.md page, perhaps just your "Introduction" and then a table-of-contents for the rest of the pages in the "Promotions" section of the documentation, similar to the format for the "Addresses" section of documentation: https://docs.drupalcommerce.org/commerce2/developer-guide/customers/addresses
-
Create a new page that immediately follows the TOC for the section, something like "Promotions information structure" or "Promotions architecture" or just "Overview", like we have for "Products" documentation: https://docs.drupalcommerce.org/commerce2/developer-guide/products/overview/product-information-structure
-
Create another new page for "Code recipes" (as the last section of the Promotions documentation). Break out code examples in this page to make the text for the overview/architecture flow more easily. Also, with respect to comments by travis-bradbury, separating code examples with specific syntax from a more conceptual discussion of Promotions as a whole would improve maintainability.
3 participants
Currently there is no documentation for the intro section to Commerce Promotions. This pull request aims to fix that.