Documentation overhaul #3138
Documentation overhaul #3138
Conversation
…freshes, consolidated docs revamp
…t in that guide, moving to "advanced" to not confuse general users
…s, WIP plugin tutorial, SS updates
Codecov Report
@@ Coverage Diff @@
## main #3138 +/- ##
=======================================
Coverage 59.45% 59.45%
=======================================
Files 671 671
Lines 28628 28628
Branches 6926 6926
=======================================
Hits 17020 17020
Misses 11286 11286
Partials 322 322
📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
|
if possible, i might like to avoid doing a large overhaul but i would like to incorporate other parts of this PR. I am thinking it may be good to avoid splitting up the guides into multiple files and subfolders because moving contents around can break our existing links. if there is a strong feeling that the long documents are overwhelming, maybe we can brainstorm a solution on that but my current feeling is to try to keep some of the contents in place |
|
@cmdcolin so if I'm reading right, the main concerns you have with this PR is that it breaks existing links, and it might be breaking the documentation into too many pages? |
|
basically yes. my thinking is influenced by jbrowse 1 with it's large configuration guide http://gmod.org/wiki/JBrowse_Configuration_Guide which gives you almost everything you need on a single page |
|
this is sort of just a "feeling" about the look and feel of the docs but the docusaurus webdesign could also be taken into account. I have thought multiple times that the web design of the docusaurus docs are a little "claustrophobic" with it's multiple sidebars on both the left and right side of the page, and that this "claustrophobic" feeling may influence a desire to break up the docs |
|
Most modern software guides have broken-up documentation in lieu of (and sometimes accompanied by) an index. That is, the left sidebar kind of operates as an index to help guide someone to the answers to their questions. Some examples: docker, AWS, Azure. This was, for example, the spirit behind breaking "using the bookmark widget" out of the "User guide" because it draws attention to a big feature that new or returning users might need a reference on; placing it in its own page makes it easier to find. The JB1 documentation, while all on one page, has a huge index that emulates this idea of accessibility to answers at a glance (i.e. it's basically the left sidebar without being on the left or the sidebar). Comprehensive summary of pages moved/changed in this PR as of right now:
Quickstart guides
User guides
Config guide
Developer guide
API
(( there are other new pages that are mostly new content and would not be involved in above feedback )) Current broken links:
Proposed solutions:
To help visualize what's in the PR right now and in this comment without spinning it up: JBrowse.org/jb2/docs presently:
With current PR changes without the proposed changed in this comment:
|
|
I acknowledge it is a common pattern to break up docs, but it is sometimes hard to define the right boundaries for what constitutes a new article. it also relies a bit on SEO or a search engine inside the docs (which we don't have) to lead people to the right place (otherwise, you have to poke through the sidebar a lot). to me, the current system, with user guide, config guide, developer guide, is at least conceptually simple because there is basically no question where new contents go (fairly straightforward to categorize new content as user, config, or developer related) for devs adding new docs, and for users looking for stuff, it is relatively clear which thing applies to them. currently, basically all main doc links are changed (quickstarts,userguide,developerguide,configguide,etc), so this is a pretty big change. of course, change can be good, but I do think stability is important because we link to docs from external sites. one way to ensure more stability is to use versioned docs but this will generate lots of contents in the s3 bucket and needs a bit of dev work to put in place. just from browsing, the docker and azure links do not have versions in their url but the aws does, pinned to latest (which means we would assume that link is somewhat stable) |
|
Most links have been reverted back and guides re-consolidated. Changes that have been maintained thus far that differs from current docs state:
These changes from the current docs state are those that I feel most profoundly enhance discoverability and clarity of our documentation without breaking existing links. That being said, I am still open to discussion on these points, and any others e.g. rewrites in the docs, tutorials, etc.
|
|
made some misc updates here https://github.com/GMOD/jbrowse-components/tree/docs-updates-merge-main
|
|
brief chat with @carolinebridge-oicr and i think this pr can be merged as is but we may move towards broken up pages in a next iteration, i do think that there is some value to breaking the pages up :) |
* quickstarts and userguides * repositioning docs, edit quickstart guides, user guide, screenshot refreshes, consolidated docs revamp * adding cancer landing page with some placeholders, userguide updates * splitting config guide to expose components that are only talked about in that guide, moving to "advanced" to not confuse general users * consolidating api guide, updating plugin guide * [update docs] userguide updates, devguide updates, faq, api, tutorials, WIP plugin tutorial, SS updates * [update docs] fixing broken links and faq * [update docs] final touches on dev tutorial 1 * no build plugin tutorial * plugin usage guides * revert changes to file structure to preserve historical links * build * Fix build complaints * Underscore in user_guide * Misc * lint and minor sidebar arrangement * moving const * hiding cancer portal until we have a refreshed video to display Co-authored-by: Colin <colin.diesh@gmail.com>
summary of changes
overall small grammar edits, emphasis, updating screenshots where critical, updating links w new structure, etc.
moving combined guide to above faq
changing name of combined guide "consolidated docs"
added jupyter page
moved url api into api, just api now w a subheader
adding internal folders to help organize better
split quickstarts into starting with cli and starting via download (downloading is technically the fastest way to start using jbrowse, might be better for general users)
moved cli config, gui config, and "superquickstart" into userguides
removing superquickstart and condensing cli guide (my justification for this is, if an admin is familiar enough with the jbrowse CLI / genome tools / webservers to be able to properly follow this guide, they're probably just going to reference the CLI commands page, otherwise they will probably need the full CLI guide, and having two is confusing)
revamped intro page to include new docs and better descriptions, linked to jbrowse jupyter documentation
split dev documentation up a bit, moved some info into tutorials
resolve Add FAQ for customizing color via GUI/CLI #2840 with additions to FAQ
resolve Plugin Documentation Refresh #2142 with new tutorials
Questions for draft:
wording/review for:
/docs/devguides/developer_guide/#renderers, line 222
I added an info block to try to help explain the relationship between views, tracks, displays, and renderers; just want to make sure it's descriptive enough, clear, and accurate.
/docs/devguides/devguide_pluggable_elements/#getrefnames line 324
There was a broken link here for reference renaming and I don't see anything related other than aliasing -- is this still a thing? changed the link to ref name aliasing