Where locate documentation

[s-martin]

Currently we have the wiki as documentation source as well as some files in docs folder and various readme files.

We already have a hard time keeping docs up to date, but multiple locations makes it more difficult.

My idea:

• Keep installation and configuration instructions for components in the respective readme file. Improve where necessary
• use wiki for general installation instruction, FAQ, spotify integration, hardware guides and howtos
• migrate content in docs folder to readme and remove the folder content afterwards

@MiczFlor, what do you think?

[s-martin]

See also #1238

[pabera]

I see the spread documentation being a blocker for people to get started. your proposed idea is great - should this be started at some point? I am happy to help a little here and there.

I would focus on the README.md first, as it is a crucial entry to the project. But then most installation instructions and FAQ should flow into the wiki for sure. it'll be easier to update for everyone if changes occur.

[MiczFlor]

I also think it's a great idea. If there was any way to automate the generation of documentation, that would be an advantage.
Usually that could mean running a script across the codebase and if all developers kept to a certain format, the documentation could be generated and then... well, added to the wiki, I guess?
Originally I thought the docs folder should contain the essentials. The wiki the more specialised stuff.
If it were to be generated automatically, I wouldn't hurt to have the documentation in two places at once - if it's always up to date.

[pabera]

There are two types of documentation - code docs and user docs. The automatic code doc generation is preferable but only describes individual aspects of your code (and might be hard to achieve). User documentation is essentially wiki - e.g. a getting started guide, a very specific setup, a migration guide.