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

Improvements to Advanced Tutorial doc #3266

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

Conversation

noramullen1
Copy link

@noramullen1 noramullen1 commented Feb 14, 2025

Fixes #3268

Summary

  • Various style and grammar updates, including the following:

    • Avoid ellipses (reference)
    • Hyphen vs. em dash (reference)
    • Key-value, not “key -> value” (reference)
    • Headings should be sentence case (reference)
    • Use the serial comma (reference)
    • Use parentheticals only when needed (reference)
    • No exclamation points (reference)
    • Use negation contractions (reference)
    • Don't capitalize feature names like dictionary (reference)
    • Consistency fixes: New York City/NYC, primary key/primary index, compute/calculate, switching between first and second person for the audience (it should always be second)
  • Remove "marketing lingo"

    • Superlative language like "blazing fast", "amazing collection", or "the s3 cleverly knows" doesn't fit with the purpose or tone of product documentation.
    • Product docs should be clear, concise, and focused on showing them how to do the task at hand.
  • Organization and user experience

    • Don't number h2s.
    • Collapsed expected output code blocks for queries section to make it more scrollable.
    • Including dictionaries link in-line instead of telling user to scroll to the bottom.
    • Link to existing description for LIFETIME instead of trying to reinvent the wheel here.
    • Use note formatting sparingly to avoid fagtigue.
    • Final section was randomly h4 nested under the Perform a join section.
  • Example says "right join" but code shows inner join

@CLAassistant
Copy link

CLAassistant commented Feb 14, 2025

CLA assistant check
All committers have signed the CLA.

@@ -486,14 +501,17 @@ Let's write some queries that join the `taxi_zone_dictionary` with your `trips`
ORDER BY tip_amount DESC
LIMIT 1000
```
:::note
Generally, we avoid using `SELECT *` often in ClickHouse. You should only retrieve the columns you actually need. However, in this example, we wanted it to be slow because why?
:::
Copy link
Author

@noramullen1 noramullen1 Feb 14, 2025

Choose a reason for hiding this comment

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

It's not clear to me why you'd want this query to be slow.


<SQLConsoleDetail />
Copy link
Author

Choose a reason for hiding this comment

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

These two giant screenshots seem extremely unnecessary and disruptive to the reader's experience.

@Blargian
Copy link
Member

@noramullen1 This is our 13th most viewed page, so thank you for the very valuable contribution! :)

Spell check is failing on these words:

====== /home/runner/work/clickhouse-docs/clickhouse-docs/docs/en/tutorial.md ======
Allerton
Boro
LocationID
Pelham
york

As they're part of a query response we just need to add them as exceptions here: https://github.com/ClickHouse/clickhouse-docs/blob/main/scripts/aspell-dict-file.txt

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.

Improve Advanced Tutorial doc
3 participants