Docs improvements

[mcnuttandrew]

The readme.md file is currently written like it is the front page of the docs, it would be good if we updated the tone (and the repo tagline, which I assert is "A COMPOSABLE VISUALIZATION SYSTEM") to be reflective of the modern state of the repo and the tone of the docs.

On the otherside of the coin, there is the single tutorial doc page which is now the lead page of the documentation on the docs-site. This feels a little weird to me. So I guess my question is there a better way to organize this front matters? Should we add more tutorials to that folder?

Finally, I think we should maybe re-ogranize the docs folder because having that many files is getting kinda cumbersome.

As a todo list

• reogranize docs folder
• select consistant spelling

[mcnuttandrew]

We should also figure out a consistent spelling of react-vis, i'm personally for down-cased kabob (react-vis)

[jckr]

Here are my plans for future work on documentation. Those could become individual issues.

• A better home page. This is probably what will require the most work. It would need:

  • to quickly make the case of what react-vis is about.
  • act as a sensible navigation hub to various parts of the documentation,
  • redirect users to deck.gl, luma.gl, react-map-gl
  • have attention grabbing examples to support its USPs,
  • a little bit of magic dust.

  the first 3 parts are easier and everything doesn't have to be done at once.

• a better getting started page.

• Getting started starts at installation, btw, but people don't need to install react-vis to play with it since you can use codepen (or equivalent, but hey uber visualization has an account on codepen so we could have most examples there too - a couple of features just don't like iframes)

• create a better structure for documentation overall. The sensible / most commonly found way to arrange the documentation pages are:
  • a tutorial section that can be read sequentially, like a book (and btw, we could publish it as an actual book);
  • a reference section to the API.
  • guides that zoom in on how to implement a specific technique,
  • a commented gallery of examples.

Today, the section headers which have grown organically don't make a ton of sense, and there's a lot of overlap between overview and XY-plot. Overview needs to evolve to be a full-fledged tutorial, with some sections moved to either API or guides. XY-plot needs to be only about the description of its API. Children of XY-plot which are not series (such as gridlines or axes) need to go in their own category.

• * Meatier documentation on the "other charts" as well as on the "examples", which belong together.

• * Much much more examples.

[balthazar]

Bump. The Ocular migration should help us in this direction.