Documenting best practices for the website

[don-code]

At the 2024/10/02 working group session, we got into a discussion about how we'd expect users of the devopsdays-assets and devopsdays-web repositories to know what to do.

Documentation today is stored in several places in Git:

• The top-level README
• The CONTRIBUTING file
• The utilities documentation
• The theme reference documentation

If we revamp our documentation, there are two key considerations:

1. How should the documentation be organized? Can we make the current documentation easier to process by a new even torganizer, by changing how it's stored and how it links to other documentation resources? For example, could it be organized by intent ("To create a new event..." or "To add a sponsor to your event..."), rather than by tool ("To make a merge request..." or "To run add_sponsor.sh...")?
2. What tool should be used to generate documentation? Proposed options were Hugo Doc, Docusaurus, and the wiki features built into Github.

[jerdog]

A revamp would be helpful, and my preference would be to see us utilize Docusaurus (easy to track changes, approvals, etc.), with the internal Wiki features as a second choice.

Utilising the way that you typically want to see documentation (Overview, Getting Started, Deeper dives, etc.) would be helpful for various levels of editors as well, and easier to process.