Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: README update to help new users #370

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

ETHenzlere
Copy link
Contributor

@ETHenzlere ETHenzlere commented Oct 1, 2023

Hey everybody,
I am a new user of benchbase and I found it cumbersome to get everything running smoothly with a lack of documentation. Therefore I have decided to update the README.md slightly, such that new users of benchbase have an easier time getting started. The documentation should now provide enough information now to get started smoothly with benchbase.

My two small additions:

  1. Prerequisites section with a direct link to the official Java 17 download page
  2. Usage Guide subsection that links to a more detailed page about how to adapt the configuration files

@ETHenzlere ETHenzlere marked this pull request as ready for review October 1, 2023 15:44
README.md Outdated Show resolved Hide resolved
README.md Outdated

```xml
<username>admin</username>
<password>password</password>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, these are the obvious ones and somewhat self explanatory.

We should probably have additional docs on what the other fields in those configs do and how to adjust them.

For instance, it's possible to run on a select set of queries, or multiple workload phases with a single config, but that isn't super obviously documented IMO.

Copy link
Contributor Author

@ETHenzlere ETHenzlere Oct 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can see that they look obvious to experienced users but they are needed for a quick-start of benchbase so I'd like to keep them here if possible :)

Do you think it would be beneficial to add a new .README file to the config folder and explain the advanced things there? - Or move everything related to config there and add a quick navigation link to the new .README file in the github README?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My point about those two parameters being obvious is that they're self explanatory once you know where to look, but the part about where the configs are may not be.

I would suggest that the Getting Started text get rewritten as something slightly more high-level like "adjusting the connection details in the config file" which includes basic commentary about both the JDBC URL and the credentials.

A separate ConfigDetails.md might be warranted that the main README.md links to for additional details, especially with external links to JDBC driver details.

I don't think the entire ConfigDetails.md is necessary for you to write here, but if you could start a stub of it with the above, then I think one of the benchbase experts can take up the rest from there.

Make sense?

@ETHenzlere
Copy link
Contributor Author

@bpkroth Hey Brian, I finally found some time to make the changes we talked about. I hope that some of the benchbase-cracks can adapt the config/README.md file with more useful information.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants