Reorganize and revise "Getting Started" docs #990
Conversation
Remove the file since the contents have been added to `docs/getting-started-with-scalardb.md`
| ## Reference | ||
|
|
||
| To see the source code for the electronic money application used in this tutorial, see [`ElectronicMoney.java`](./getting-started/src/main/java/sample/ElectronicMoney.java). |
There was a problem hiding this comment.
In the original document, we showed the source code of ElectronicMoney.java. However, the code shown in the doc was different than the code in the .java file.
To avoid needing to update the source code for ElectronicMoney.java twice (in the source code and in the doc), I've simply added a link to the source code as a reference.
| Now we can run the application. | ||
|
|
||
| - Charge `1000` to `user1`: | ||
| - Credit **1000** to **customer1** by running the following command: |
There was a problem hiding this comment.
I changed user1 to customer1 because a customer-merchant relationship is common in commerce.
|
|
||
| For a list of databases that ScalarDB supports, see [Supported Databases](scalardb-supported-databases.md). | ||
|
|
||
| <div id="tabset-1"> |
There was a problem hiding this comment.
This <div> begins the tabbed content for the four databases.
| scalar.db.password=<PASSWORD> | ||
| ``` | ||
| </div> | ||
| </div> |
There was a problem hiding this comment.
This </div> ends the tabbed content for the four databases.
| {% capture notice--warning %} | ||
| **Warning** | ||
|
|
||
| This electronic money application is simplified for this tutorial and isn't suitable for a production environment. | ||
| {% endcapture %} | ||
|
|
||
| <div class="notice--warning">{{ notice--warning | markdownify }}</div> |
There was a problem hiding this comment.
This is a notice/warning for users. I've added other notices to this document as well, which follow the same syntax.
To see what a notice looks like, please see PR #990 (comment).
josh-wong
requested review from
komamitsu,
brfrn169,
choplin,
feeblefakie and
Torch3333
There was a problem hiding this comment.
LGTM! Thank you!
@josh-wong To which branches would you like to apply the changes?
@choplin True! We currently have an index page (titled "Setting Up Your Database Environment" in the side navigation) that points to individual pages for configuring the four databases. Since that index page and the individual four pages are in one doc (as of this PR), I agree that "Configure ScalarDB for Your Database" would be better. I've updated the title of the doc in this PR. |
@brfrn169 I'd like these changes to apply to the |
Rename `getting-started-with-scalardb.md` to `configuring-scalardb-for-your-database.md` to match the title of the document.
Rename `configuring-scalardb-for-your-database.md` to `configure-scalardb-for-your-database.md`.
| @@ -0,0 +1,243 @@ | |||
| # Configure ScalarDB for Your Database | |||
There was a problem hiding this comment.
@josh-wong @choplin I'm not sure this title is appropriate.
The goal of this document is to provide introductory steps for new users to get started with ScalarDB, but I don't think the goal is to explain how to configure ScalarDB. We already have a separate document addressing that. So I think the title Getting Started with ScalarDB is more appropriate. What do you think?
There was a problem hiding this comment.
@brfrn169 I see your point. Since we have another document that describes how to configure a database in detail, I'm OK with changing the title of this document back to "Getting Started with ScalarDB."
In addition, we also have other "Getting Started" docs for features in ScalarDB that are similar to this one. If we decide a different title is more suitable later, we can always change it.
There was a problem hiding this comment.
I also think Getting Started with ScalarDB is more appropriate. Let's change it!
we also have other "Getting Started" docs
Which ones?
Maybe, we need to rename them appropriately.
There was a problem hiding this comment.
@feeblefakie Sorry, let me clarify. The other docs I was referring to already have "Getting Started ..." in their titles (for example, Getting Started with ScalarDB Analytics with PostgreSQL).
In the future, if we decide to not use "Getting Started" for this "Getting Started with ScalarDB" doc, we should keep in mind our other docs that have "Getting Started" in the title (like the one above) so that we can maintain consistency.
There was a problem hiding this comment.
@brfrn169 @feeblefakie IMO, from the "Getting Started" page, we would expect a more comprehensive step-by-step explanation of how to start using the software, from downloading, and configuration to getting an initial result, which is to query the database in our case. I said "too general" because this page only contains the configuration part of the process to start using ScalarDB.
There was a problem hiding this comment.
@choplin In addition to the configuration section, the page also contains the following sections:
Create and load the database schema:
https://github.com/scalar-labs/scalardb/blob/c089fe1b0219db53b0daa3a6b0b0d4149d52e258/docs/getting-started-with-scalardb.md#create-and-load-the-database-schema
Execute transactions and retrieve data:
https://github.com/scalar-labs/scalardb/blob/c089fe1b0219db53b0daa3a6b0b0d4149d52e258/docs/getting-started-with-scalardb.md#execute-transactions-and-retrieve-data
Do you still consider this to be "too general"?
There was a problem hiding this comment.
@brfrn169 Ah, sorry that I misunderstood what page we are talking about. I said "too general" for the pages mentioned in the description of this PR, like https://scalardb.scalar-labs.com/docs/latest/getting-started-with-scalardb-on-cassandra/.
There was a problem hiding this comment.
@choplin Understood. So let's keep this page title with Getting Started with ScalarDB. Thank you!
| @@ -0,0 +1,243 @@ | |||
| # Configure ScalarDB for Your Database | |||
There was a problem hiding this comment.
I also think Getting Started with ScalarDB is more appropriate. Let's change it!
we also have other "Getting Started" docs
Which ones?
Maybe, we need to rename them appropriately.
|
@brfrn169 Thank you for merging this PR! Can we also apply the changes to branches |
@josh-wong The auto-PR workflow, which automatically creates PRs for the support/release branches, has failed: Can you please create PRs for this change manually, targeting the branches |
|
@brfrn169 Got it. Will do! |
Description
This PR reorganizes and revises the instructions in the Getting Started docs. Within a single page, users can read how to get started with ScalarDB by selecting their database, which are shown as tabs on the docs site.
Related issues and/or PRs
N/A
Changes made
I copied the contents from the individual Getting Started with [Database] docs and added the contents as tabs to a single page. Since those individual docs are no longer with this single doc, I deleted those pages.
I also revised the content and added notices to highlight certain sentences for users.
Testing done
I ran our docs site locally and confirmed that the all-in-one Getting Started with ScalarDB page appeared as expected. For example, the following screenshot shows Cosmos DB for NoSQL selected as the database and a note.
Checklist
Additional notes (optional)
None.