add the get-started documents - Githubissues

scylladb / scylladb-docs-homepage

Source for docs.scylladb.com site

https://docs.scylladb.com

0 stars 1 forks source link

add the get-started documents #5

Closed annastuchlik closed 7 months ago

annastuchlik commented 8 months ago

This PR adds documents that cover basic concepts in ScyllaDB and help developers get started with ScyllaDB.

In addition, the left navigation bar is enabled in this project so that the new documents are shown in the page tree.

annastuchlik commented 8 months ago

@dgarcia360 Please have a look to see if everything is OK in terms of our toolchain, customization, etc.

tzach commented 8 months ago

Visual comment: the combination of left menu and cards does not work well

tzach commented 8 months ago

Some initial comments on the content, starting with Key Features page: It's to marketing. in docs, we need to

provide 100% accurate info on the product.
add a reference to each of the claims.
High Performance and Scalability - these are two different items! Performance is a result of the share per core architecture and other optimizations. Scalability is a result of the ring architecture. Since we already have Horizontal Scalability below, we can remove it from here.
Fault Tolerance: the result of eventual consistency, Raft...
Efficient Caching: not clear.
Comprehensive Monitoring: link to the monitoring project

As is, the Use Cases section is too vague to be part of the docs.

"Big Data Analytics: Ideal for applications requiring real-time processing of vast datasets." This is not true. Scylla is not a good tool for pure "Big Data Analytics". Scylla is a good tool for real-time processing (OLTP), which can also support concurrent Analytics requests.

tzach commented 8 months ago

Can we use Tabs in the Driver page, as in the Connect an Application? It would make the page more compact and make the "CONNECT AN APPLICATION" more visible.

tzach commented 8 months ago

data-modeling/query-design/ - We should remove it or add examples to make it worthwhile. Without examples, it is a collection of high-level statements that are hard to use. BTW, we have a Scylla U course on data modeling we can link to.

tzach commented 8 months ago

/data-modeling/schema-design/

An advantage of NoSQL databases such as ScyllaDB is the perception that schema design can evolve.

Relational database supports ALTER TABLE for decades. Lets avoid such statements, they are not helping the user to use the product.

timkoopmans commented 8 months ago

Some initial comments on the content, starting with Key Features page: It's to marketing. in docs, we need to

provide 100% accurate info on the product.

add a reference to each of the claims.

High Performance and Scalability - these are two different items! Performance is a result of the share per core architecture and other optimizations. Scalability is a result of the ring architecture. Since we already have Horizontal Scalability below, we can remove it from here.

Fault Tolerance: the result of eventual consistency, Raft...

Efficient Caching: not clear.

Comprehensive Monitoring: link to the monitoring project

As is, the Use Cases section is too vague to be part of the docs.

"Big Data Analytics: Ideal for applications requiring real-time processing of vast datasets." This is not true. Scylla is not a good tool for pure "Big Data Analytics". Scylla is a good tool for real-time processing (OLTP), which can also support concurrent Analytics requests.

scrapping that section as I feel it's hard to get right for this getting started guide / doesn't offer a lot of value to developer at this point in onboarding.

timkoopmans commented 8 months ago

/data-modeling/schema-design/

An advantage of NoSQL databases such as ScyllaDB is the perception that schema design can evolve.

Relational database supports ALTER TABLE for decades. Lets avoid such statements, they are not helping the user to use the product.

scrapped in latest comments for something shorter / less snakeoil

timkoopmans commented 8 months ago

data-modeling/query-design/ - We should remove it or add examples to make it worthwhile. Without examples, it is a collection of high-level statements that are hard to use. BTW, we have a Scylla U course on data modeling we can link to.

more examples added

annastuchlik commented 7 months ago

@timkoopmans @tzach Please re-review. I've merged Tim's suggestions and added the examples. I think that all comments left by Tzach are now addressed.

Here's how the content is now organized:

The menu in the left sidebar is removed.
New to ScyllaDB? Start here! is presented as a button. Also, the search box is removed (we already have a search bar in the right corner, so this one was redundant). All that for better visibility.
Later on, we can improve the design and position of the button with David's help. I've used what is available now.
The pages are grouped under a new Get Started with ScyllaDB page. It will enable us to add pages that don't belong to Getting Started in the future if needed.
We can have another iteration to improve it. For example, the "ScyllaDB Documentation" label is not necessary here. But I think we can release as is.

annastuchlik commented 7 months ago

I've skipped the critical information: the button now takes you to https://docs.scylladb.com/stable/. After this PR is merged, I'll open another one to replace it with https://docs.scylladb.com/stable/get-started, as the URL doesn't exist yet.

annastuchlik commented 7 months ago

@tzach Tim and I are done reviewing. I've also asked @zseta and @DanielHe4rt to have a final look at the driver-related pages. Can you re-review and let us know if you think the PR can be merged?