Navigation properties need documenting

[kirsty-hames]

Subject of the issue

There's been a few recent navigation enhancements that have gone into Core which haven't been documented.

• Navigation sorting order - see PR issue/3281 Added data-order to buttons for sorting navigation #61
• Tooltip API (button tooltips) - see PR New: added tooltip API (fixes: #193) #207
• Navigation button API (button text labels) - see PR New: Added Navigation Button API #339
• Navigation settings: _isDefaultNavigationDisabled, _navigationAlignment and _isBottomOnTouchDevices.

[swashbuck]

A page for the Tooltip API has been started here by @StuartNicholls
https://github.com/adaptlearning/adapt_framework/wiki/Tooltips-in-Adapt

@kirsty-hames Where should the Navigation documentation go? Should we start a new top-level page for "Navigation"? Where would people most likely look for it?

[kirsty-hames]

Should we start a new top-level page for "Navigation"? Where would people most likely look for it?

Hey @swashbuck, I can't see we have an existing place for documenting core code. This might be better queried in a new ticket but should we be documenting core config in the core readme? Like we do for other plugins.

If we just want to document on the wiki though then creating a new page makes sense to me. I find the pages aren't the most intuitive on the wiki as it's a collapsed menu so easily missed but useful for those who already use the wiki and know where to look.

[swashbuck]

This might be better queried in a new ticket but should we be documenting core config in the core readme? Like we do for other plugins.

@kirsty-hames That is an interesting idea. I imagine we'd want to include all properties listed in the schema files at src/core/schema Yeah, maybe a new core ticket would be good for this? I don't know if there's a reason why we're not updating the core readme.

If we just want to document on the wiki though then creating a new page makes sense to me. I find the pages aren't the most intuitive on the wiki as it's a collapsed menu so easily missed but useful for those who already use the wiki and know where to look.

Yeah, it's definitely not ideal, but there's a lot of useful stuff there (if you know where to look, as you said). I think we could go ahead and create a Navigation page there. Then, depending on the outcome of the core readme issue, update it there as well? Although, with the core Vanilla theme, I believe we're just focusing on keeping the Wiki updated rather than the theme's readme.

[oliverfoster]

There is no reason why the core readme is not updated. It would be a very long readme. It is needed. Please proceed if you wish to. Good idea.

The wikis are traditionally more how-to-ish.

Both readmes and wikis are good if you find use for them. No-one is currently owning the documentation tasks. Any efforts are welcome, there are no hard rules.

[kirsty-hames]

Yeah, it's definitely not ideal, but there's a lot of useful stuff there (if you know where to look, as you said). I think we could go ahead and create a Navigation page there. Then, depending on the outcome of the core readme issue, update it there as well? Although, with the core Vanilla theme, I believe we're just focusing on keeping the Wiki updated rather than the theme's readme.

Hey @swashbuck, I quite like the Vanilla theme approach. As Ollie mentioned, it would be a very long readme to include all core config. Containing links to the relevant wiki pages is a good shout. If you're happy with this approach I can raise a ticket on Core?

[swashbuck]

If you're happy with this approach I can raise a ticket on Core?

@kirsty-hames Sure, thanks for raising!

[kirsty-hames]

Navigation wiki page created and currently being worked on.

[kirsty-hames]

Navigation wiki page complete.

[swashbuck]

Thanks, @kirsty-hames . It was very much needed :)