Documentation party :tada:

[luucvanderzee]

This is currently planned for the 22nd of March, but that is still negotiable. If the party is planned during the day I can probably join in near the end, and then go through all the diffs after everyone in SG goes home, to make small corrections/fix style consistencies?

Before we start, however, we need to make some rules on styling to keep everything consistent. I suggest the following rules, based on my own preferences and what I have enforced so far:

Titles/headers

1. Avoid long titles or headers, and avoid characters besides normal letters and spaces
2. Avoid repeating headers/titles
3. Only use a capital letter for the first word, but not for every word. So Some header is fine, Some Header is not.

1 and 2 here exist so that you can link to paragraphs from other files with <file>.md#some-header without any problems

Structure

1. Try to keep the structure the same for similar things. So, all documentation pages for components should have the same structure, just like all pages for statistical transformations, and all pages for concepts, etc.
2. For the component docs: make sure there is always at least a Component tag, Description, and Props header, and optionally a Usage header. It is ok to put shorts examples of usage in the Props header if that seems appropriate, but limit the (complex) examples as much as possible to the Usage header.

Props table

1. In the documentation pages for components (Core and Marks), there is always a Props section that contains one or more tables that document the props. Make sure these tables always have a Prop, Required, Types, Default, and Description column. Make sure these are always spelled in the same way, with a capital letter. The Units column is optional and should only be used if there might exist confusion about what the units are, like local coordinates vs screen pixels. BTW: this one is not consistent right now, because it is sometimes called Unit(s), so we should still make that consistent.
2. The Prop column: here we mention the kebab-case name of the prop. So line-width instead of lineWidth. If we mention the prop name in the text below the table, we also use the kebab case version, AND we use backticks to highlight the name.
3. The Required column: can only be true, false, or depends. If the value is depends, the text below the table must describe under what conditions the prop is allowed, and when the prop shouldn't be used.
4. The Types column: if only one type is allowed, we should use for example Number. If multiple types are allowed, we use [ and ], so for example [Number, String]. When we talk about types in the the text below the table, we always use a capital (so for example, "the prop can be passed String data if so and so...").
5. The Default column: Can be a value or undefined.
6. The Description column: Must be a 1-sentence description. If that is not enough, use the text under the props table for a longer description. The sentence must start with a capital letter, but should not end with a punctuation mark.
7. The Units column: should be Screen pixels, Local coordinates, or something else, but keep it short.

Other guidelines:

1. If you end up explaining sometimes many times in different parts of the documentation, consider makig a new page under Concepts. It is good to reuse concepts, because it will be easier for us and our users to reason about the logic behind the library if we have concepts that return in different places and always work in the same way. See the Scaling concept for an example.

Any other guidelines? Or any suggestions on improving the ones I just proposed? Also, should we add a documentation label to the GH issues?

[bianchi-dy]

Some suggestions based on what I observed from the Interactive Data Vis class using vue-gg for the first time:

1. Perhaps we should include simpler examples of how to input values (without scaling, just the values themselves) into some of the marks, like Multiline and Trail. So we'd put 'simpler' examples of mark definitions like:

<vgg-data :data="data">
   <vgg-multi-line
       :x=" 'x' "
       :y=" 'y' "
       :stroke-width="4"
       fill="green"
  />
</vgg-data>

before showing any fancier stuff involving mapping, dataframes, scales, etc. This could also be more an issue with Vue literacy.

2. There was also some confusion on what format the data needs to first be in before plugging them into the components. For example, using chartData.json which creates the ff graph on the left using vgg-point or vgg-symbol:

requires a data input with the ff format:

chartData = [ { x1, y1 }, { x2, y2 }, ...]

whereas creating the chart on the right with vgg-multi-line or other continuous marks requires the ff format:

chartData = { x: [ ... ], y: [ ... ] }

I am not sure if this is something that should just be addressed in the class itself or if it is worthwhile to include in the docs.

[luucvanderzee]

In reply to @bianchi-dy her comment above:

1. Just to be clear, the example you're showing there is outdated :stuck_out_tongue: this is from way before we did the v-slot syntax. Besides that, I wasn't at the class, but I would definitely start with just mapping the values without any scaling, and only later introducing the scaling. You could do something like: 'look, we have the values 1-100, so we will map these to the pixel values 50 - 150. But what if we wanted to map them to 50 - 350 instead? Well, with a bit of math, you can calculate exactly by what you would have to multiply the original value. And guess what: vue-gg let's you do this automatically with this handy scaling syntax!'

As for 2., we will make some strides here tomorrow!

---

I compiled a small todo list of stuff that was still in the back of my mind for tomorrow:

• [ ] Finish the first page of the docs, about what the grammar of graphics is, and how we use it
• [ ] Add some installation instructions
• [ ] Walk the user through the construction of some basic graphs to get a feel for how to use the library (scatterplot, bar chart, faceting, repeating, one of each)
• [ ] Finish the docs for all Marks
• [ ] Finish the docs on the Section (still some stuff missing there)
• [ ] Finish the docs for the individual transformations
• [ ] Right now, the 'data loading' docs is kind of spread out between the 'Data loading' concept and the 'Data component' core component docs. Maybe better to move as much as possible of this to the 'Data loading' concept
• [ ] Document the scales better- which scales exist for which props and which data types?
• [ ] Document the 'band' option that is used to create bar charts
• [ ] Get rid of the split between 'axes' and 'guides' and just put everything under 'guides'
• [ ] Delete the 'positioners' header for now

Anything else?