Additional documentation topics

[cmdcolin]

• CLI - loading different synteny formats
• User guide - Faceted track selector
• User guide - LGV Basic usage: double click to zoom
• SV inspector: after adding breakpoint split view, show that you have to manually open up tracks https://jbrowse.org/jb2/docs/user_guides/sv_inspector_view/#launching-breakpoint-split-view
• Dotplot: toggling ctrl wheel
• Developer guide: display type https://jbrowse.org/jb2/docs/developer_guides/creating_display/ and track type https://jbrowse.org/jb2/docs/developer_guides/creating_track/ and view type https://jbrowse.org/jb2/docs/developer_guides/creating_view/
• Storybook: document the usage of trackId for text indexing (mentioned by @kuffelgr on chat) done
• Maybe a special section on configuring "displays": configure default height, configure color, and explain the "displays" section of the configs more?

[cmdcolin]

also, more "tutorials" like https://github.com/GMOD/jbrowse-components/pull/3449

[cmdcolin]

another doc topic, plugins https://github.com/GMOD/jbrowse-plugin-template/issues/30

[cmdcolin]

may be a good example for jexl docs https://github.com/GMOD/jbrowse-components/discussions/3603#discussioncomment-5470742

[carolinebridge]

• improve the embedded tutorial to be more practical for generating visualizations and using the .view functions
• on the "features" page, specify which file types are supported by the embedded views

[cmdcolin]

just for context, @carolinebridge-oicr and i were talking in chat just about the setup of jbrowse with the overture team, etc. I think the embedded deployment is difficult for a number of reasons

• unclear how to load tracks (does not really use jbrowse-cli)
• difficult to hand write track configs. how can we simplify? we could make a little helper that calls guesstracktype/guessadaptertype for an array of filenames or something, e.g. make a 'simplified config format' but this creates a sort of 'parallel config schema'... or we can take larger efforts to make our standard config models simpler to instantiate (use of preprocessSnapshot to fill in things automatically perhaps?)
• several of our examples explain to 'hand configure a defaultsession' which I think is really not recommended
• need to, if not using defaultSession, call imperative APIs like showTracks, could add helper function to make it so that createViewState accepts a 'defaultTracks' type argument (this was decided against long ago, but could be reconsidered). if we don't do this, I think it is worth making more clear through more examples that using the view functions (like showTrack) is the recommended way to do things, as I don't think hand-coding the defaultSession is a good experience.

[cmdcolin]

also, it may be worth steering people to our working examples e.g. storybook and embedded_demos over the tutorial page

[carolinebridge]

I know we have the state model reference, but I think for anything embedded view relevant we should have a separate, clearly documented API for things like showTracks. Could link out to the storybooks too.

[carolinebridge]

• maybe adding nice error reporting to the embedded tools like we have for jbrowse web (e.g. for bad configs, what is actually wrong)

[cmdcolin]

example for variation track color https://github.com/GMOD/jbrowse/issues/937#issuecomment-1534326753

[cmdcolin]

advanced example of config (setting color, etc) at https://jbrowse.org/jb2/docs/config_guides/quantitative_track/ (recommended by veupathdb)

[cmdcolin]

Update docs with HiDPI screenshots...many are low res

[cmdcolin]

bookmark docs need updating http://jbrowse.org/jb2/docs/user_guides/bookmark_widget/

[cmdcolin]

connections https://github.com/GMOD/jbrowse-components/issues/2765

[cmdcolin]

improve synteny docs https://github.com/GMOD/jbrowse-components/issues/3270

[carolinebridge]

do we have enough discoverability in our documentation for cross-regional visualizations / data rendering? we've got a ton of support for it at this point might be worth having a dedicated page for it in our user guide

yes could be worthwhile, or at least expanding documentation around the features that use this mode

per https://github.com/GMOD/jbrowse-components/pull/4045

[cmdcolin]

paired bedpe display needs docs

[cmdcolin]

• Document @jbrowse/react-app interaction with CLI
• Document how to add track programmatically in @jbrowse/react-app
• Document "embedded views" vs "full jbrowse app" vs "embedded @jbrowse/react-app" (on website features page)

[cmdcolin]

address https://github.com/GMOD/jbrowse-components/issues/3280

[cmdcolin]

Review quickstart guide: this is an important document, and in the middle it switches from using npx serve to --out /var/www/html/jbrowse2 without explanation

https://jbrowse.org/jb2/docs/quickstart_web/

Also review this repo's README.md. could be made more minimal, as people might find it, thinking they need to apt install things when they dont really

[cmdcolin]

I also still think there is value in making a superquickstart. it could be made into a TLDR at the top of the quickstart. this was, at one point, deleted but i think it helps to orient someone about a cli workflow without a lot of prose. it is hard to scan the document at a high level

[cmdcolin]

the quickstart also does not have links to example files. it could essentially mirror the protocols paper, but with smaller files

[cmdcolin]

possible idea; use an ai to aid documentation process. AI can generate a bunch of plausible looking stuff, lowering the barrier to just getting it done. we have not established guidelines about using AI generated content in our project but if it is acceptable, it might be worth trying out

[cmdcolin]

• document PIF
• document (or add to every code example?) memo-izing createViewState in embedded. need to decide 'best' memoize method if adding to all

[cmdcolin]

mention in various places where plugins are documented e.g. https://jbrowse.org/jb2/docs/tutorials/no_build_plugin_tutorial/ that embedded apps can use a different technique