[DOCS-16285] [SERVER] Add internal use note to explain's slotBasedPlan field description Created: 31/Jul/23  Updated: 16/Jan/24  Resolved: 08/Jan/24

Status: Closed
Project: Documentation
Component/s: manual, Server
Affects Version/s: None
Fix Version/s: Server_Docs_[20240116]

Type: Task Priority: Minor - P4
Reporter: Eric Sedor Assignee: Matthew Maville
Resolution: Done Votes: 0
Labels: quick-win, request
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Participants:
Days since reply: 7 weeks, 2 days ago
Story Points: 2

 Description   

To the slotBasedPlan field description here can we please add:

"This field is for internal use by MongoDB engineering during support engagements as needed."



 Comments   
Comment by Matthew Maville [ 18/Dec/23 ]

Adding eric.sedor@mongodb.com for external review of changes.

Comment by Matthew Maville [ 14/Dec/23 ]

Tagging christopher.harris@mongodb.com for comment now that we having a staging preview. I think the clean up of the links is great and that the note we found is sufficient for the internal use notice. Just want to ensure we're fully on-board with not adding the internal only note to slotBasedPlan on the product side as requested in the original ticket.

https://preview-mongodbmmavillemdb.gatsbyjs.io/docs/DOCS-16285-slotBasedPlan-internal-only-note/reference/sbe/#check-query-explain-results

Comment by Jeffrey Allen [ 12/Dec/23 ]

matt.maville@mongodb.com, those are good findings and considerations. I think it's confusing that in the Check Query Explain Results section we link to the same Explain Results page three times (each to a different anchor point).

 

As part of this update, it might be helpful to reduce those links down to a single link. My initial idea is to remove the initial link to "explain results" (replace with plain text) and the "explain.queryPlanner.winningPlan.slotBasedPlan" link (replace with monospace text), and only retain the link to the "Explain Output Structure" that appears at the end of the section.

 

I don't think we necessarily need to include the "This field is for internal use by MongoDB engineering during support engagements as needed." blurb in the "Check Query Explain Results" section. IMO, only having that blurb appear where we define the field itself on the Explain Results page is sufficient.

 

Just going to tag christopher.harris@mongodb.com here in case he has opinions from the product side of things.

Comment by Matthew Maville [ 12/Dec/23 ]

While looking for the source file for this issue, I also found that Check Query Explain Results references using slotBasedPlan (and subsequently links back to the Explain Results page referenced by this ticket, albeit at a different anchor point).

Worth mentioning that the ref on Check Query Explain Results leads to a note that states:

  • Some fields are for internal use and are not documented."

Looking for additional guidance due to this external consideration.

Comment by Sarah Olson [ 01/Aug/23 ]

That makes a lot of sense. Sounds good.

Comment by Jeffrey Allen [ 01/Aug/23 ]

In my opinion, we should retain the docs for this field because users will still see this field in the explain output. I think if users see this field and can't find any info about it, that's not a great experience and could lead to questions through the feedback widget.

Comment by Sarah Olson [ 31/Jul/23 ]

Thanks eric.sedor@mongodb.com. Would it be better to simply remove documentation for this field? If we don't want customers to use it, I'd love to omit documentation all together. WDYT? 

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