Automated documentation workflow improvements

Auto updating docs is a pretty great feature. But has some trade-off of slightly unclear dev process, and some limitations with the docs we display on design.gitlab.

Some issues we ran into on pair call:

Lots of files to create

When creating a new component, there are a lot of steps to follow for creating/editing boilerplate content. Docs for this could be better (sometimes filenames etc are unclear). We can automate setup with !121 (merged) - it's still valuable to have explanations of "here's what this file is for" and "here's how this thing works", as it's currently a bit of a mish-mash of magic files. Or to reduce the need for magic files (either with more magic, or by manually updating design.gitlab docs).

Or throwing errors more frequently. The one for GlComponentDocumenation is missing from component_generator is a great example of an easy-to-fix error.

Duplicated with stories

I think we should only have one of examples or stories. Generate stories from examples is possible solution for this.

Is it less likely to be stale?

Someone updating code will likely update adjacent _docs file

• will they though? Code can be changed and comments aren't updated. This seems just as easy to miss without adding checklist item

Overall docs quality not better

• Component Docs SSOT is unclear. What should go in component.md here vs in Pajamas repo?
• Docs in gitlab-ui are not usually written far beyond "This is component X used for Y"
• Design of component docs pages in Pajamas is kinda limited. You can't control location of the examples. That's determined by componentinfo.vue in design.gitlab. Being able to embed components in the markdown could lead to more complete examples. e.g. explanation followed by a relevant code example.