While working on #3021 (preview here) I got a bit stuck in writing.

I realized that there basically is a difference between documentation that explains how to do things and documentation that explains why you should do certain things. When these two aspects are integrated into a single page, eg. demonstrating how to change color schemes and explaining the significance of selecting appropriate colors you get a single very lengthy page.

I think this is another example (other) of how docs are used differently at study and at work.

After reading a bit more on systematic approaches of writing technical documentation, (this website was very interesting) and discussing this topic a bit more with @joelostblom and my not-yet-on-github-colleague Michelle Rudolph, we think it could be interesting to add a section in the documentation on best practices for data visualization using Altair.

The current User Guide has a section navigation with two items. We think it might be worth discussing to add another section so it becomes:

• How-To Guide (this is currently titled User Guide)
• Conceptual Guide (new)
• Advanced Usage (same)

Time-wise its not really possible to have a single PR with a complete new section in the docs, so it's probably best to approach this iteratively. Maybe starting with a skeleton structure that slowly can be filled in.