Uploaded image for project: 'Drivers'
  1. Drivers
  2. DRIVERS-341

Drivers should use https://docs.mongodb.com/master/ for documentation permalinks

    XMLWordPrintableJSON

Details

    • Icon: Task Task
    • Resolution: Done
    • Icon: Major - P3 Major - P3
    • None
    • None
    • None

    Description

      I've had some discussions with kay.kim in DOCS-9162 and more recently offline about how drivers docs should permalink to server docs. Now that we've just shipped, I'd like to make a driver-wide proposal for how to do this consistently in the next cycle.

      Our chicken-and-egg problem:

      • Drivers documenting new or changed server features want to link to the official server manual for details.
      • Server documentation changes won't be published in the database manual until the server ships.
      • Drivers want to ship/publish documentation before the server ships to allow testing against development releases.

      Recommended solution:

      How it would work:

      • When new server docs are written, they are immediately visible in the 'master' URL.
      • Drivers link to 'master' URLs so that users can see and use docs during testing.
      • When the server ships, 'master' and 'manual' URLs have identical content.
      • Eventually, 'master' diverges to add new features or changes for the next server release.

      Pros:

      • Drivers only have to write documentation URLs once.
      • New-feature documentation readily available for RCs before server ships.
      • No race to update URLs from 'master' to 'manual' right at ship time.
      • No tickets to update them from 'master' to 'manual' later after the server team ships (i.e. no "doc patch" release necessary).

      Cons:

      • The 'master' will periodically diverge from 'manual', meaning drivers will sometimes be pointing users to an "in development" version of the manual.

      Personally, I think the "con" is minor: the server version the manual applies to is visible on the page and many features will have no divergence from release to release anyway.

      Attachments

        Activity

          People

            bernie@mongodb.com Bernie Hackett
            david.golden@mongodb.com David Golden
            Votes:
            0 Vote for this issue
            Watchers:
            6 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: