Documentation feedback

Tags: #<Tag:0x00007fd2e0638f48>

Hello,

First of all, congratulations HoT team for a fantastic component with a lot of power! I’ve been building and finessing our collection of HoT table components, factories and helpers, and of course heavily using the HoT docs for about 6 months now, and I have some comments.

Please take these as constructive feedback, and not criticism. They are from the POV of someone who has gone from noob to power user, needing more and more information, and hopefully you will see the value in these suggestions to help folks like me get the most out of the table.

Consider separating the Guide and API

Both the Guide and API have a lot of information in them, and it feels like they could both do with perhaps a bit more structure.

I don’t know how the API docs are collated, but I presume some kind of automation?

Perhaps separating them would allow different build processes and perhaps different navigation / search if needed.

Please include some lifecycle diagrams

As your table needs become even slightly advanced, you need to know where to start, and what the flow will be from then on (methods, hooks, etc). Right now, it’s very difficult to know where to start, and after you’ve started, what happens. All you can do currently is trawl the docs or use search.

The members of this section should be intuitive for table users (i.e. break things out by area, rather than by plugin) and should form the basis for the rest of the docs.

I’d suggest one diagram per major feature, i.e.:

  • bootstrap
  • core
  • cell edit
  • validation
  • selection
  • copy & paste
  • columns / rows

Each diagram should include relevant methods called and hooks fired.

Where necessary, flows should link to other flows.

I know there can be a LOT of hooks fired (I logged 3000+ with one experiment) so clearly a way would need to be found to make this presentable:

init
afterInit
modifySourceLength
modifySourceLength
afterGetRowHeaderRenderers []
modifyRowHeaderWidth 0
modifyColHeader 0
modifyCol 0
afterGetColumnHeaderRenderers [ƒ]
modifyCol 0
modifyRow 0
modifyCol 0
beforeGetCellMeta 0 0 ColumnSettings {row: 0, col: 0, visualRow: 0, visualCol: 0, prop: "bloomberg", …}
afterGetCellMeta 0 0 ColumnSettings {row: 0, col: 0, visualRow: 0, visualCol: 0, prop: "bloomberg", …}
modifyColWidth undefined 0
modifyCol 1
...

Having the APIs in alphabetical order is not useful

This follows on from the lifecycle discussion. We need:

  • uses / operations
    • operation (i.e. bootstrap, plugin, etc)
      • options
      • methods
      • hooks

Again, this should be really obvious.

Right now, you get afterCoreThing, afterPluginXFoo, afterPluginYBar and it’s just a soup of functions you have to go through 1 by 1. This is really unintuitive if you have an idea on how to solve something, but don’t know what is related and what is not.

Plugin events should be listed with their plugins, not in core

It’s really frustrating to have to core filled up with random methods!

See the above.


That’s about it for the time being.

I’m actually compiling my own list of categorised methods and hooks, which I will use as my reference, and it’s been really interesting to get to know the library in-depth.

It would be great if this was just available as a reference in the core docs.

Anyway, thanks for reading!

Cheers,
Dave

Hey @dave.stewart

we should copy/paste it to the /docs repository as any ideas on the forum get lost easily.

It great that we’re discussing this now as (starting hopefully next month) we’ll be doing some serious /docs adjustments.

I did think about creating an issue there, but thought it might not get seen!

Shall I copy this over now?

Yes, we’re gathering issues from https://github.com/handsontable/vue-handsontable-official/issues/100 and https://github.com/handsontable/docs/issues for our new collegue to make the docs more dev-friendly.

Done:

1 Like