The documentation is far from idiot-proof

Documentation Is:

• [x ] Missing or needed
• [x ] Confusing
• [x ] Not Sure?

Please Explain in Detail…

Let’s say you are completely new to ChartJS and want to build a line chart. After reading the installation and getting started pages, you might sensibly visit the Charts > Line page: https://www.chartjs.org/docs/latest/charts/line.html

The example chart on the page looks great. How would you implement that in your own html page? Well look there is example code right underneath it.

var myLineChart = new Chart(ctx, {
    type: 'line',
    data: data,
    options: options
});

Right… ok that’s fine but what am I supposed to put in the data or options fields? The next section is labeled “Dataset Properties”. This seems relevant but I’m not really sure how it relates to the data field above. Right at the bottom of the page there is a heading called “Data Structure” which starts:

The data property of a dataset for a line chart can be passed in two formats

Ok so you might think this is referring to the missing data field above and then you might try to do this:

var myLineChart = new Chart(ctx, {
    type: 'line',
    data: [20, 10],
    options: options
});

But of course, even if you were to give a valid options value this would not work…

Your Proposal for Changes

Please define the data types for the data and options fields. What properties do they accept? Where can I find this information? Please reference these datatypes in all the locations where they are needed such as the first example code of the Line documentation. Don’t assume a newcomer has any knowledge besides what has been explained in the Getting Started pages.

If this is not possible to do then please supply more full examples. Why not give the full source for the line chart that is shown at the beginning of the line chart documentation?

This is just one example of a page that could be improved, however I find myself constantly lost while looking at the chartjs documentation. For example, looking at the “Performance” page I noticed a property called ticks.sampleSize. So thinking lowering this value might improve performance on my chart but I simply have no idea on which object this property exists. It seems likely to be on the ticks object of the common configuration of some axes object - however this is not explicitly stated neither is it stated how to specify the common axes properties.

[benmccann]

We would also need to think about how to display options that can go in multiple places. E.g. options.lineTension vs options.elements.line.tension vs dataset[0].tension (I’m just mentioning from memory and might have those paths slightly wrong). We might have a hard time doing this without tackling some of the other options cleanup work from the 3.0 tracking ticket.

If you want a list of all options under options then your best bet is probably to look at the TypeScript type definitions: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/96ffa5c08b8f6c880098d139a900164a47a0f077/types/chart.js/index.d.ts#L276

This might be one good reason for us to adopt TypeScript more broadly. It could help a lot with these types of questions

[sebiniemann]

So thinking lowering this value might improve performance on my chart but I simply have no idea on which object this property exists.

This alone is always the most confusing part for me and I believe it simply arises from the way the information is presented.

Most of my colleagues frequently ask whether something goes into [dataset]. or options. and which additional keys are needed until the actual parameter can be set.

Looking at https://www.chartjs.org/docs/latest/configuration/layout.html for example, the information is clearly there:

The layout configuration is passed into the options.layout namespace.

But most of the time, the eyes immediately skip to the table (one might even scroll down, completely hiding the first sentences) and only seeing: padding.

What happens next is usually confusion, followed by searching stack overflow for a code example 😄

The issue I see here is that the current documentation implicitly assumes that people read/study it top to button and that most things need to be told only once.

What I however usually see is jumping straight into any page from a quick google search, quickly scanning for promising looking snippets/paragraphs that might answer the question somebody has and only focusing/reading these particular parts.

Having all that said, my suggesting would be to write options.layout.padding instead of padding (i.e. always starting with the root object) within parameter lists, repeating every time where exactly a parameter has to be set 😃