The documentation is far from idiot-proof

[alexspurling]

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]

Have you seen the samples https://www.chartjs.org/samples/latest/ with full examples?

[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 😃

[JLuc]

Not sure i'm an idiot (AMOF I dont think so) but found the "migration" link wrong in the readme : https://www.chartjs.org/docs/next/getting-started/v3-migration.html is 404

[benmccann]

@JLuc what readme are you talking about? I don't see a link to the migration guide in https://raw.githubusercontent.com/chartjs/Chart.js/master/README.md

[JLuc]

Oups sorry it's in Breaking Changes of https://github.com/chartjs/Chart.js/releases/tag/v3.0.0-alpha

[etimberg]

@JLuc sorry about that. I've updated the link to point to the correct spot

[alexspurling]

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 smiley

Thanks for this suggestion - it would be a big improvement over the current documentation. Even better if each of the breadcrumbs would link to the table that defines the other properties that object might need.

I should add at this stage, taking another look at the documentation, I cannot find the page that defines the available properties of the options field. You would think it would be on this page but this doesn't mention the scales property which I have seen in some examples: https://www.chartjs.org/docs/latest/general/options.html

Where is the documentation that describes options?

[etimberg]

I played around with the fully qualified names. The first image shows with options at the beginning vs the 2nd where it is omitted. I'm not sure what is better. One potential downside of the 1st is confusion about the global options. i.e. Chart.defaults.xxx or Chart.defaults[chartType].xxx.

Fully Qualified

Partially Qualified

Re the options page, I think that might be improved by removing that page from underneath "General" and renaming "Configuration" to "Options". That way everything underneath "Options" would be in the Chart options. We could move the documentation about global options, scriptable options, etc to the first page of what is now "Configuration".

[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

[etimberg]

tension is an odd one as I think options.lineTension was only kept for backwards compatibility (if it still exists).

We actually document tension twice:

• option config: https://www.chartjs.org/docs/master/configuration/elements#line-configuration
• dataset config: https://www.chartjs.org/docs/master/charts/line/#dataset-properties

I think that's the best way to handle options like that. It might be worth linking the dataset option to the corresponding config option page. That would reduce any duplicate info

[etimberg]

Going to close this; it's been a while since it was filed and we have continued to update the documentation since that point. We also now ship TS type definitions that common editors can pick up for autocomplete which will help the understanding of where options go.