Managing documentation for the whole project

[josebolos]

The current documentation for all the pa11y projects has a number of problems that cause pain for the users and more work for us.

The problems as I see them are:

• Documentation for each of the projects is independent, even for projects strongly related like pa11y-ci and pa11y, which means at best, having users going back and forth between both documentations, and at worst, users not being able to find how to do something because the relevant bit of documentation belongs to the other repo. Plenty of examples of issues been created over the years in pa11y-ci or pa11y-dashboard and pa11y-webservice because some of the relevant information was in a repo further down the dependency chain.
• Broadly speaking, the documentation that we have doesn't really cover the 4 main types of documentation (Tutorials / How-to guides / Explanation / Reference). We have no tutorials at all that are part of the official docs, so people tend to rely of third-party tutorials, many of them published 5+ years ago and not kept up to date. The rest of the documentation is a mix of the other 3 types.
• The website is underutilised. We have a few "blog-like" entries, but the latest dates from 2018, and content is very sparse. It contains very little content that counts as documentation.

Potential improvements:

• Create a single online location for documentation, for all the pa11y projects. How this works from a technical point of view is to be decided.
• Split the documentation into 4 clear groups (Tutorials / How-to guides / Explanation / Reference).
• Create new tutorials and how-to guides covering most common use cases. This will probably help increase usage, and end up with less support questions in github and Slack created. It would also allow us to remove references to third party tutorials that may not be working any more from our site.

I'll add more ideas if I can think of anything else.