[DRIVERS-341] Drivers should use https://docs.mongodb.com/master/ for documentation permalinks Created: 29/Nov/16  Updated: 02/Nov/18  Resolved: 28/Jul/17

Status: Closed
Project: Drivers
Component/s: None
Fix Version/s: None

Type: Task Priority: Major - P3
Reporter: David Golden Assignee: Bernie Hackett
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
related to DRIVERS-227 Just link to MongoDB Manual for write... Closed

 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.



 Comments   
Comment by Bernie Hackett [ 29/Nov/16 ]

PyMongo makes heavy use of "dochub" links. Those redirects are supposed to work for forever. Has that fallen out of favor?

https://github.com/mongodb/mongo-python-driver/blob/3.4.0/bson/objectid.py#L16

My concern is that non-dochub links will break at some future date.

Generated at Thu Feb 08 08:21:18 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.