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

Add short description of all projects to start of readme #1881

Closed
idg10 opened this issue Mar 1, 2023 · 6 comments · Fixed by #1933
Closed

Add short description of all projects to start of readme #1881

idg10 opened this issue Mar 1, 2023 · 6 comments · Fixed by #1933

Comments

@idg10
Copy link
Collaborator

idg10 commented Mar 1, 2023

The discussion at #1868 (comment) has revealed that the repo-level readme file does not do a great job of guiding people who arrived at the repo (perhaps via the link on NuGet) without knowing very much about Rx. It's not obvious what's in here, and why there are several apparently different features in different libraries all in one repository.

We need a succinct description of the things that are in this repository. It contains:

  • Rx.NET (aka System.Reactive)
  • LINQ for IAsyncEnumerable (aka System.Linq.Async)
  • Ix.NET (aka System.Interactive)

These are somewhat different things (although they're conceptually united under "LINQ to everything" and more specifically "LINQ over sequences of things" which is why all three are in the same repo). So we should add a brief "What's in here, what's it for, and where do I look next to find out more?" section, answering those questions for each of the three things above.

@idg10
Copy link
Collaborator Author

idg10 commented Mar 6, 2023

While we're updating readme files, we should look at https://devblogs.microsoft.com/nuget/write-a-high-quality-readme-for-nuget-packages/

@idg10
Copy link
Collaborator Author

idg10 commented Mar 10, 2023

We also get a load of warnings when we publish to NuGet about the use of the deprectated <iconUrl>. We should update to the current practice.

@idg10
Copy link
Collaborator Author

idg10 commented Mar 10, 2023

Consider also adding a badge for the latest preview build https://img.shields.io/nuget/vpre/System.Reactive.svg

@idg10
Copy link
Collaborator Author

idg10 commented Mar 11, 2023

While we're at it, add a change log for the v6.0 release

@idg10 idg10 added this to the Rx 6.0 milestone Mar 11, 2023
@WhitWaldo
Copy link
Contributor

I fully agree the home README could use a rewrite to make it easier for new developers to understand the purpose of the various things in the repo and better understand how they might be used for one reason or another. Rxjs does a great job of this on their Getting Started page outside of the repo.

I'd follow RxJs's lead and build out a Getting Started/API Docs site somewhere on which you can replicate something like their explanations of the different Observable components, show some marble diagrams illustrating how the different operators work and generally get into more detail about each of the libraries in the project.

Here in the repo, I think having a richer description for Rx, Ix and System.Linq.Async would do wonders, especially if you can point to the Getting Started page to identify content for new users about what exactly observables even are. While there's a paragraph and table under A Brief Intro that sort of gets into this, I think it does a poor job of illustrating the different problems each of the projects in this repo intend to solve (I mean, there are three projects in the repo and this table has two rows, so that's already confusing in itself).

idg10 added a commit that referenced this issue May 16, 2023
The release notes resolve #1909

The readme update partially addresses #1881
@idg10 idg10 linked a pull request May 16, 2023 that will close this issue
@idg10
Copy link
Collaborator Author

idg10 commented May 16, 2023

We are currently working on bringing a site with a more comprehensive guide to Rx.NET up to date. (There's an existing site, and we're working to update it, with permission from the original author.) Once that's ready I'll add links as you suggest. Meanwhile, we will have richer descriptions for each element as you describe, which will be an improvement for the time being, until we're ready to release the updated guide site.

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

Successfully merging a pull request may close this issue.

2 participants