Add links to docs in all the samples #10308
Conversation
There was a problem hiding this comment.
Few comments but there are more points like them.
I think it would be a lot better to keep the lists as short as possible, will make it less maintanance intensive and it will make it so users can spot what they are looking for faster instead of seeing lot of duplicate info or nested tree of info.
So I think it would be best to keep it as minimum as possible and only list the specifics that that specific sample tries to show.
| @@ -48,3 +48,8 @@ module.exports = { | |||
| ## Log2 axis implementation | |||
|
|
|||
| <<< @/docs/scripts/log2.js | |||
|
|
|||
| ## Docs | |||
| * [Data structures (`labels`)](../../general/data-structures.html) | |||
There was a problem hiding this comment.
Guess it's better to leave these kinds (duplicates for almost all charts) out unless its something special. Because otherwise you will need to put a verry long duplicated list here for almost every sample with also things like the legend, tooltip, scales
There was a problem hiding this comment.
Particularly I pointed out labels every time because personally I find using month names as labels misleading for me as a user looking for ideas working with Date data.
| ## Docs | ||
| * [Axes scales](../../axes/) | ||
| * [Common options to all axes (`stacked`)](../../axes/#common-options-to-all-axes) | ||
| * [Stacking](../../axes/#stacking) |
There was a problem hiding this comment.
Would only list the stacking
|
|
||
| ## Docs | ||
| * [Axes scales](../../axes/) | ||
| * [Common options to all axes (`stacked`)](../../axes/#common-options-to-all-axes) |
There was a problem hiding this comment.
stacked part is unecesarry since they are common to all axes and now it looks like its only common to all stacked axes
| * [Tick Context](../../general/options.html#tick) | ||
| * [Data structures (`labels`)](../../general/data-structures.html) | ||
| * [Axes Styling](../../axes/styling.html) | ||
| * [Tick Configuration](../../axes/styling.html#tick-configuration) |
There was a problem hiding this comment.
Keep it as simple as possible, only list the tick config because thats what it is about, not the axis styling
|
|
||
| ## Docs | ||
| * [Line](../../charts/line.html) | ||
| * [Options](../../general/options.html) |
There was a problem hiding this comment.
Does not add anything, lower 2 parts do
|
My idea is that there should appropriate links to describe everything (ish) a sample plot does, even if it isn't the subject of the plot. So even if something applies to most plots, I think it still belongs to be pointed out in the links section. Because properties can be explained in many places in the documentation, its nice to know that these are the places worth looking. When looking at samples I feel like I'm reverse engineering them. I want that to be as simple as possible and have all the relevant resources on hand. I drew an arbitrary line at things like background color style and said those didn't need pointed out all the time. "everything (ish)". Often if I linked to a section just to point out one property I spelled it "Foo ( It could be worth adding a style to links that are the focus of a sample. Still might have been a couple of cases where I linked something not actually relevant. I'm coming at this as a person who only used 2.0 once at the end of 2020. I defiantly do not have familiarity with the library. |
|
And highlighting the one comment reply I made just in case: #10308 (comment)
I feel kinda strongly that using months as labels makes the samples worse. I'm just making it easier to glance and see that they're not coming from data values; they're explicitly being provided. |
If that is what you want I miss info in some places like in programatic events you dont mention the labels, in the data decimation sample you should link to the object notation then. Same with the animtions/loop example. You putted the tooltip in there while the sample is not about it, and with your current filosophy I get that, that everything that is in there must have a link to the docs but then I think you also need to put links to things like the border color etc. It feels kind of weird for me atm. Some things are verry detailed while others are not. Not consistent with the information that is provided with that everything that is used should be documented (which I still am against since it will give big christmas trees which I think will have the opposite effect as just the basic link to what the sample is about) |
|
Probably best would be to have a christmas tress at the bottom and some short prose explaining the sample at the top with inline links. A couple already have intro prose but most don't. |
|
Well my goal was only to make a first draft and get a ball rolling. I'll leave final implementation to maintainers. You can close this pr and start from scratch if you want. |
For #10295