-
Type: Task
-
Resolution: Done
-
Priority: Major - P3
-
None
-
Component/s: None
-
Labels:None
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:
- Drivers use https://docs.mongodb.com/master/ as a permalink prefix
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.
- related to
-
DRIVERS-227 Just link to MongoDB Manual for write concern and read preference semantics
- Closed