Documentation for contrib modules on docs site

[yorkshire-pudding]

At Backdrop Live 2024, we discussed how we could better do documentation for contrib modules. GitHub Wikis has been the default, but this has shortcomings:

• None of the content in the Wiki is accessible to search engines which makes it harder to find from Google/Bing etc
• Finding information within the Wiki can be challenging
• Editing long pages on the Wiki can be challenging

While other solutions were considered, the preferred approach is to make the docs site a suitable home for contrib documentation. There are a number of challenges with the docs site for contrib, that are eloquently described by @stpaultim in the Ubercart Issue Queue :

I agree that it's theoretically 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.

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.

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.

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 documentation to docs.b.org, that's great.

In summary, I believe the must haves are:

• a drafting workflow (e.g. the Content Moderation module) so people can draft new revisions without them going live straight away.
• Suitable permissions so contrib maintainers (and Bug Squad?) can moderate and publish new pages and changes to existing pages
• Improved editor experience. Markdown is available but the body field does not have the ability to be edited full screen.
• Ensure it is easy to add code blocks. Having to do <code> tags is not as easy as the markdown on github where you can use three backticks and the language to get a syntax highlighted block
• Make it easy to embed videos so they size responsively
• Force each change to be a revision (Enforce Revision Logs module) and enable easy comparison (Diff module).

Hopefully this ticket can start the conversation.

[nattywebdev]

This appears to be a very wise way to go forward and I would be happy to support it.