Skip to content

Conversation

@merlin-quix
Copy link
Contributor

@merlin-quix merlin-quix commented Feb 27, 2023

Updated the READMDE so that the libraries features are more prominent and understandable with code samples to illustrate how they work

Also split out lower-priority information into supplementary topics. For example:

  • "What is time series data?" -> what-is-timeseries.md — many readers won't need this information so better to not let it clutter the main READMDE.
  • "Installing on M1/M2?" -> mac-m1-m2-install.md — again, this is currently "workaround" documentation (also very lengthy) and wont concern many readers (on Windows, Linux, or Intel Mac)
  • "Architecture Notes" -> arch-notes.md — supplementary information that wont interest everyone.

Additionally, the "Prepare your Kafka Cluster" section did not provide any information on how to prepare anything, rather it's purpose seemed to be simply to communicate the message "We use Kafka".

I reworked this section to provide basic instructions for a local Kafka install to help people test the library quickly.

Copy link
Contributor

@tbedford tbedford left a comment

Choose a reason for hiding this comment

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

Not reviewed all of it, but noticed the code in the README now seems to be for an old version of the SDK?

@peter-quix
Copy link
Contributor

Not reviewed all of it, but noticed the code in the README now seems to be for an old version of the SDK?

Yeah, I think before we review this readme it would worth updating it to latest

@tomas-quix
Copy link
Contributor

Are you sure putting Getting started after library features?

@merlin-quix
Copy link
Contributor Author

Are you sure putting Getting started after library features?

No - It doesn't have to be. I can reorder if you want. The "real" Quick Start is in the online docs anyway (which I am linking to)

@merlin-quix
Copy link
Contributor Author

Not reviewed all of it, but noticed the code in the README now seems to be for an old version of the SDK?

Yeah, I think before we review this readme it would worth updating it to latest

Would be good to review it next to the announcement copy as both are designed to use the same feature lists w/ samples.

@PatrickMiraP
Copy link
Contributor

New arch-notes.md file is not correctly linked to the Readme. For instance where we are saying "Quix Streams is designed to be extended to multiple programming languages.".

Probably Contribution Guide section could be another good place to link to the new file.

@SteveRosam
Copy link
Contributor

Docs build including this branch is here:
https://quixdocsdev.blob.core.windows.net/pr91/sdk-intro.html

@PatrickMiraP
Copy link
Contributor

About removing "What is time series data" after "What is Quix Streams" section, there are some thoughts here in slack https://quixworld.slack.com/archives/C01U8DHH67J/p1677656326060989?thread_ts=1677218529.712249&cid=C01U8DHH67J

If we return it to the main readme, I will keep it in the same position. This section only makes sense to improve the context of "What is Quix Streams".

@srosam srosam force-pushed the docs/readme-cleanup branch from 13d578c to 13efa52 Compare March 1, 2023 13:36
@srosam srosam force-pushed the docs/readme-cleanup branch from 5b7d9db to c74a5c6 Compare March 1, 2023 16:17
Copy link
Contributor

@peter-quix peter-quix left a comment

Choose a reason for hiding this comment

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

The Readme.md regressed in several places talking about output and inputs, etc.

@peter-quix peter-quix merged commit d9b6c8b into main Mar 1, 2023
@peter-quix peter-quix deleted the docs/readme-cleanup branch March 1, 2023 19:05
tim-quix pushed a commit that referenced this pull request Nov 14, 2023
[Task/31413] - Fix README and CONTRIBUTING
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.

9 participants