Provide help text on using cart links

[herbdool]

It takes a bit of searching in the code to find out how cart links work. We should add some more help text in the configuration.

I had to enable the display of the cart link code when adding the product. Then I saw in the code that the URL structure is /cart/add/$cart_actions and found out that the code goes on the end of that like: /cart/add/p30355_q1.

[herbdool]

As a start, I've added a wiki page for it: https://github.com/backdrop-contrib/ubercart/wiki/Cart-Links.

[bugfolder]

More documentation is good, but I'm wondering if splitting it between the GH wiki and https://ubercart.dev/ is the best way to go about it. Should we strive to consolidate in one place (and if so, which)? @stpaultim @yorkshire-pudding @albanycomputers

Or just put copious cross-links?

[yorkshire-pudding]

I haven't used Ubercart (yet) so don't have a strong stake in this, however:

• We had a discussion at Backdrop Live about trying to add a space for documentation on docs.b.org. In my opinion the docs site is still lacking in ease of editing. We talked about adding Content Moderation, how we do permissions for editing, improving the editor experience, and I also suggested we use Enforce Revision Logs. Nothing much has happened other than the Documentation stream in Zulip
• GitHub Wikis are with the module, but are not searchable via the internet whereas an internet site is.
• If we do have documentation in more than one place, there should be an obvious split, not just who writes it.

[herbdool]

I agree it's probably best on docs.backdropcms.org, if we can set it up properly.

[bugfolder]

In my opinion the docs site is still lacking in ease of editing.

At least now we can use Markdown on docs.b.org, which should help.

Perhaps there should be an issue on https://github.com/backdrop-ops/docs.backdropcms.org/issues to capture that B-live discussion?

[stpaultim]

I agree that it's theoritically best to have a single place for this documentation and docs.backdropcms.org would be a good place for that, if the folks that need to use it have the access and the tools are available that they need.

I've said it many times, that while I love to help with documentation. I'm very reluctant to contribute documentation to docs.backdropcms.org, for a number of reasons.

1. It feels very "official" and formal. I'm more at ease contributing documentation in a less formal location. One of the advantages of ubercart.dev is that it has the feel of a bottom-up community project that one does not have to be an expert to contribute to.

2. There is no "draft" mode on docs.b.org. If I make changes there, I don't have a good way to hold my changes until someone approves them or to ask for a review. I'm making direct changes to "official" documentation and depending upon the subject matter, I'm not always comfortable with that.

3. If there are tools/modules I'd like as an editor on ubercart.dev, I'm pretty sure I can ask Steve and we'll just go ahead and add the module with very few restrictions and limitations. We can do that, because we're an independent community driven site. When I edit docs on "official" backdrop sites, I'm restricted by the tools and modules that have been approved by those sites and we tend (for very reasonable reasons) to be VERY conservation about adding modules to our official sites.

In short, I'm fairly convinced that we don't get better documentation on our docs site, because it's not very welcoming to new folks or folks who don't feel like they are experts. One of the advantages of ubercart.dev is that the threshhold for participating there is very low (I think).

While I think the the official docs sites could be the best place for Ubercard docs, that is not true unless the folks inclined to work on documentation feel comfortable working there and have access to the tools they need. I've very reluctant to tell folks that they shouldn't write documentation, unless they do it on the docs site, for fear that I'd just be discouraging contribution.

These are solvable problems, but until we solve them. We might want to let people create documentation anywhere that feels comfortable for them. I think it's more important that documentation exists somewhere, then it is important it exists in a special place.

I think that my biggest ask for the docs site would be to get some kind of workflow tool installed there. Personally, I'll be much more comfortable posting there when I can edit a page, but keep the edits in draft mode, until someone else looks at them.

In the meantime, I love to create documentation in less formal places and then if anyone wants to copy my documenation to docs.b.org, that's great.

We really need to get @albanycomputers involved in this discussion. He created ubercart.dev for a reason, I'd like to better understand why he made that decision.

[yorkshire-pudding]

In my opinion the docs site is still lacking in ease of editing.

At least now we can use Markdown on docs.b.org, which should help.

Perhaps there should be an issue on https://github.com/backdrop-ops/docs.backdropcms.org/issues to capture that B-live discussion?

@bugfolder @herbdool @stpaultim @albanycomputers - I've added an issue here:
backdrop-ops/docs.backdropcms.org#243