[DOCS-11553] BI Connector docs inconsistencies Created: 06/Apr/18 Updated: 29/Oct/23 Resolved: 16/Apr/18 |
|
| Status: | Closed |
| Project: | Documentation |
| Component/s: | BI Connector |
| Affects Version/s: | None |
| Fix Version/s: | None |
| Type: | Improvement | Priority: | Major - P3 |
| Reporter: | Mariano Escribano | Assignee: | Steve Renaker (Inactive) |
| Resolution: | Fixed | Votes: | 0 |
| Labels: | None | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original Estimate: | Not Specified | ||
| Participants: | |
| Days since reply: | 5 years, 44 weeks, 5 days ago |
| Story Points: | 0.25 |
| Description |
|
Working through an issue the other day, I encountered three inconsistencies in the BI connector docs. First, under https://docs.mongodb.com/bi-connector/master/launch/#mongosqld-as-a-system-service for Windows, the systemLog path is using linux syntax instead of a drive letter and backslashes, just like in the green NOTE box under it which is correct. Second, in the example immediately following the above, we have the steps to install and run the mongosqld service:
This has proven confusing for at least one customer and it looked like one single command wrapping to the next line (novice mistake, but still). Preferably, it should read like this:
Note how I also wrapped the config path in quotes, since the path may contain spaces and will result in errors for the customer if those spaces are not escaped. Alternatively, we could simply provide another green NOTE box explaining the issue with spaces so they can adjust as needed. Finally, the --mongo-sslPEMKeyFile explanation here https://docs.mongodb.com/bi-connector/master/reference/mongosqld/#cmdoption-mongosqld-mongo-sslpemkeyfile seems pasted over from a similar flag used in the mongod docs, hence the lingering reference in he description to mongodb. I believe this should read something like:
Thanks! |
| Comments |
| Comment by Mariano Escribano [ 06/Apr/18 ] |
|
I am more of a Linux person myself so I cannot say what will look OK to most Windows users unfortunately. However, simply spacing those two commands apart like you suggested should be enough. This particular point is more of an edge case caused by a novice system admin in general who couldnt interpret that properly, but it doesnt hurt to tweak it up to avoid the issue entirely. Your example for the PEMKeyFile verbiage should be good. I simply wanted to make it clear who the cert is meant for, because the hostname the cert is issued with will have to match the host where the mongosqld runs. As far as the first item with the systemLog path syntax, assume that one is pretty clear. Thank you! |
| Comment by Steve Renaker (Inactive) [ 06/Apr/18 ] |
|
Hi Mariano – thanks for the feedback. Regarding the Windows instructions for starting mongosqld as a service, I'll add a line break there to make it clearer that there are two separate commands involved, and add quotes around the path to the config file. Are most Windows users OK with multi-line commands delineated with ^? I'm never sure which syntax works with which Windows shells (cmd, PowerShell, etc). Regarding the --mongo-sslPEMKeyFile option, what do you think about this verbiage: "Specifies the .pem file containing both the TLS/SSL certificate and key for mongosqld to use when connecting to MongoDB." The important thing is for users to understand the difference between the --mongo-sslPEMKeyFile and --sslPEMKeyFile options, which is a tricky thing to convey. |