created by Geraldine_VdAuwera
on 2018-01-04
With less than a week to go before the big day (aaaaaaah), we’re putting the finishing touches on some important updates to the website and the documentation.
Starting Tuesday Jan 9, the primary supported version will be 4.0, so all the documentation displayed by default on the website will be the 4.0 documentation. That covers not just the [Tool Docs](https://software.broadinstitute.org/gatk/documentation/tooldocs/current/), which have always been systematically versioned, but also the forum-based peripheral docs that are more general and typically do not change from one version to the next. In the case of the move to GATK4, a majority of these peripheral doc articles are affected by a range of changes, from minor points of syntax to major shifts in functionality (e.g. switching from `-nt`/`-nct` to Spark for multithreading). Here’s how we’re planning to deal with that.
——
In order to preserve access to a GATK3-compatible form of the not-traditionally-versioned documentation (because we recognize that moving to 4.0 is a non-trivial change), we have cloned ALL THE DOCS! This allows us to freeze the originals for perpetuity (or however long we have until the Machines take over) and to update the clones freely as we move into the GATK4 era.
In practice what this means is that there will be two parallel set of docs on the website. The GATK4 set will be displayed by default, while the GATK3 set will be accessible through either a button or a drop-down menu (exact UI still TBD because it would be boring to have everything ready way ahead of time). If we ever switch to GATK5 during my lifetime (I might be psychologically ready in another 20 years), we will use the same mechanism then. And in case you’re worried/wondering, ALLEXISTING LINKS WILL REMAIN VALID. But we’ll add a note at the top of all GATK3-era docs to make it clear that they are the legacy version. We will probably not be able to put in a direct link to the replacement doc, at least not in the immediate future, because there are so many of them and so few of us but we might try to get that done (or crowd-source it) down the road.
HOWEVER. Not everything will coexist in this two-state-solution form: there will be a few things that change permanently to be GATK4-only on the website.
- The [Quick Start Guide](https://software.broadinstitute.org/gatk/documentation/quickstart) (formerly Getting Started) will be GATK4-only.
- The [Best Practices](https://software.broadinstitute.org/gatk/best-practices) documentation will also be GATK4-only, although there will be versioned workflow implementations available that will make it possible to go back in time if needed.
- [Pipelining Options](https://software.broadinstitute.org/gatk/documentation/pipelines) will be consolidated to only cover Cromwell and WDL, so no more talk of Queue please (may it rest in peace).
- [Version History](https://software.broadinstitute.org/gatk/documentation/version-history) will be essentially the same thing but with a facelift.
- [Presentations](https://software.broadinstitute.org/gatk/documentation/presentations) (including tutorial materials) from past workshops will remain available indefinitely — or until all of Google’s storage space gets filled up with BAM files.
- [Bugs & Feature Requests](https://software.broadinstitute.org/gatk/documentation/issue-tracker) (previously Issue Tracker) has been GATK4-only for some time so that will continue. I’m not super happy with the setup we have for that section so further improvements may be in the works, but not for a little while. Feel free to suggest ideas.
The other sections of the website will be mostly unchanged, save for some freshening up. The one real change is that everything related to licensing will be updated, thank goodness, since in the brave new world of GATK4 everything is open-source (huzzah!); and the [Download](https://software.broadinstitute.org/gatk/download) section will look a bit different, though it will still provide access to older binaries. Oh, and before I forget, the “Documentation” section will now be called “User Guide” (as it was for a while a long time ago) because survey says it’s what people prefer.
There will also be a migration guide that specifically points out key differences between GATK3 and GATK4 to help ease the transition… but that’s a story for another time.
Updated on 2018-01-04
From mglclinical on 2018-01-15
Thank you for the post @Geraldine_VdAuwera