Readme update #866

TimonPost · 2020-10-12T14:25:10Z

Live version

https://github.com/TimonPost/quinn/tree/timon/read-me-update

Changes

- Grammer fixes
- Remove Usage Notes, will be moved into the book.
- Add project logo
- Add 'Getting Started' section with suggested links and short instructions.
- Update draft version
- Transform a list of library-creates into the table.
- Combine features and status into one single feature-list
- Add Authors and License section

You can open the logo file with https://www.photopea.com/ which is free without accounts and or licenses.

Discussion

~~I removed the cryptography and buffer section since it will be added to the book.~~
~~The features list and the status list seemed very similar to me, I think they can be combined into one single list, perhaps there are reasons to keep it as the old way?~~

- Add 'Getting Started' section with suggested links and short instructions. - Remove Usage Notes, will be moved into the book. - Transform list of library-creates into table. - Combine features and status into one single feature-list - Add Authors and License section

djc · 2020-10-12T14:47:23Z

I kind of like the logo, though I'd want to look into copyright/trademarks a bit more. Please don't remove any content from the README until it's added back somewhere else, though (as I mentioned already in the tracking issue).

We should probably update the statement about it being ready "for experimental use". Also, we're at draft 29 now. The Cargo.toml doesn't make much sense to collapse to me, since it's so short, but maybe it doesn't make sense to have at all, since it's pretty obvious to any potential user.

Merging status and features somehow probably also makes sense.

Agree that we shouldn't spend much space/time on my talk and or the history of the merge anymore.

TimonPost · 2020-10-12T15:35:32Z

Thanks for the review. I will remove the cargo toml, and add those two sections back.

So that's an important point that you mentioned: "for experimental use", what would you like to see in this place? In what stage is Quinn? Like QUIC is already used by more than half of all connections from the Chrome web browser to Google's servers. Microsoft Edge and Firefox support it. And I heard it is possible to use it for youtube as well.

TimonPost · 2020-10-12T15:53:53Z

The logo is used over here: https://quicwg.org/, I can find it on many other blog posts or quic related websites.

Over here are the original resources:

https://github.com/quicwg/wg-materials/tree/master/badge

There is a commit from 8 days ago with the message 'Delted LICENSE'

quicwg/wg-materials@9749588

So it seems like there is no license on it, hence we can use it until they have.

I asked a question over there to the person whom removed the license:

quicwg/wg-materials@9749588#commitcomment-43176318

…n, up-date current draft.

Ralith · 2020-10-12T20:56:33Z

So it seems like there is no license on it, hence we can use it until they have.

Unfortunately, copyright law dictates that if there is no license specified, you do not have permission to do anything with it. It's also common for standards bodies to want careful control over their branding so it doesn't get associated with work they don't intend to endorse.

Ralith · 2020-10-12T20:58:58Z

Maybe it's time to get rid of, or at least boil down, the fine-grained feature list, also? That dates from when most QUIC implementations were significantly incomplete; these days if you just say "quinn is a QUIC implementation" then the rest is implied.

djc · 2020-10-13T07:39:55Z

You mean the what's currently the Status list? Yeah, I think getting rid of that makes sense. But let's keep what we currently have as Features, though we should add a note that our HTTP/3 support is still experimental.

TimonPost · 2020-10-13T13:15:23Z

Good point @Ralith, I will fiddle around with some other logo-ideas such that we will not have to deal with those copyright issues.

If there are more points to be added or removed from the features list, please let me know. Perhaps it can be nice to add a statement that it is fully async compatible.

djc · 2020-10-13T13:27:02Z

I think we should remove the checkboxes in this case, since they're all checked anyway.

djc · 2020-10-13T20:43:15Z

So reviewing the new version you have so far:

I don't think we should spend so much vertical space on the logo. That's prime real estate wasted on a lot of whitespace.
I think we should probably move what's currently called "Features" into the top level introduction, before "Getting Started". This answers the all-important question -- what is this project (and to some extent, what are its values).
I think overview comes next: this answers the question, how is the underlying design available to users, and what layer would make sense for the reader's use case. I'm not sure the table is adding much value here; I think I personally prefer the bullet point list from the old version, though we could make the crate names bold rather than monospace to make them stand out a bit more. (If we're going to keep the table, I think each description should start with a capital letter and end with a period.)
After this, the getting started. Probably prioritize the Examples over the Links for now, as it seems more actionable.
I think we should add @stammw as an author, maybe as "Project collaborator, author of the HTTP/3 implementation"?
I don't think we need to mention the licensing again in the text. It's present in the badges up front and also linked from the sidebar, and we fit in with the ecosystem standard anyway.

…started; Add Jean as colaborater/author; Change to new logo, and reduce vertical height; Add capital letter and period to overview

TimonPost · 2020-10-14T12:46:57Z

Thanks for the review, I updated all your feedback points. As for the overview table.

I also added a new logo. Please let me know what you think of it. I'm not a very good designer but given some feedback and some time I will be able to get something nice for QUINN. Since the org requires the logo for a profile picture, this has become a necessity.

I played along with some variations, I like this one more. The lines in the logo circle represent connections, it seems technical, and it symbolizes streams and endpoints. The strike through line represents time, progress, fast, speed.

TimonPost · 2020-10-16T13:04:07Z

Is this good to go now, any opinions on the logo, and or extra comments on the content?

djc · 2020-10-23T12:19:29Z

I have some nits about the logo. Mainly the spacing seems pretty uneven, in particular the distance between Q and u is much larger than between the other letters. I also wonder how the space between the Q and the circle relates to other spacing (maybe should be a bit more), and I feel that the whitespace on the inside of the circle (between the circle and the other thing) should increase a little bit. It also looks like the horizontal white line throughout the letters is thicker than the spacing between the letters, which feels wrong.

Also, please add the logo as an SVG. I don't have Photoshop and am unlikely to have access.

(Honestly, the logo doesn't seem all that important to me, so focusing on the content first and leaving the logo for later also seems like a fine option to me.)

I think you didn't really respond to my previous remark about table vs bullet list for the overview.

Let's not have periods after the Links items, and only have a single capital per bullet there. Also, lower-case Owner in the Authors section.

TimonPost · 2020-10-23T15:41:23Z

Thanks for the second review!

Logo

Yes to a certain degree the logo is a secondary item. Tough I would really recommend it, in my view it makes the library look way more professional even if it is a simple logo with just the name 'Quinn' in some special font. And after all the logo is already worked on, so unless you totally don't like it, it's a small effort to make the changes as described. If you really don't want or like it we can remove it and focus on it more at a later stage. All perfect for me 👍 .

I don't have Photoshop and am unlikely to have access.

I use https://www.photopea.com/ which is free and almost identical to photoshop

I think you didn't really respond to my previous remark about table vs bullet list for the overview.

Imo the table version looks cleaner but it isn't that big of a deal to change it to a bullet list. I will go for the bullet list and change it back as it was.

Let's not have periods after the Links items, and only have a single capital per bullet there. Also, lower-case Owner in the Authors section.

For the lower-case 'Owner' I think we should maintain the English grammar rules and maintain the rules for capitalized titles. Thus instead capitalizing Creator and Collaborator which is currently not correct.

…able to list; Remove periods links.

…dd more space in the circle; Ensure strike trough line is evenenly sized as space between letters; Change Q spacing;

djc · 2020-10-24T12:31:41Z

I use https://www.photopea.com/ which is free and almost identical to photoshop

It looks like that can also export to SVG, so let's use that and store it as SVG. SVG is scalable and can be used on the web as-is, whereas PSD is a proprietary file format that cannot be used on the web.

For the lower-case 'Owner' I think we should maintain the English grammar rules and maintain the rules for capitalized titles. Thus instead capitalizing Creator and Collaborator which is currently not correct.

I don't see how it makes sense to use title capitalization for the project roles.

TimonPost · 2020-10-24T14:44:03Z

Cool, I will export it to SVG 👍

I don't see how it makes sense to use title capitalization for the project roles.

It makes sense as in that it is according to the English grammar rules which state that (job) titles that should begin capitalized every other word. You can check sites like https://titlecaseconverter.com/, https://capitalizemytitle.com/, out to validate this grammar.

djc · 2020-10-27T08:32:46Z

It makes sense as in that it is according to the English grammar rules which state that (job) titles that should begin capitalized every other word. You can check sites like https://titlecaseconverter.com/, https://capitalizemytitle.com/, out to validate this grammar.

@Ralith you maybe reluctant to weigh in on this particular bikeshedding argument, do you have an opinion as the only native speaker on our team?

Ralith

I agree with @djc that the terms in question do not constitute formal job titles; rather, they're plain adjectives, which should not be capitalized.

Ralith · 2020-10-31T18:14:30Z

README.md

+- All feedback welcome. Feel free to file bugs, requests for documentation and
+  any other feedback to the [issue tracker][issues].
+- The quinn-proto test suite uses simulated IO for reproducibility and to avoid


I'd drop the bullet points here in favor of a paragraph break.

@TimonPost if you process this I think this is ready to merge!

Great, @djc I progressed this in 1fa2a43 yesterday.

On https://github.com/TimonPost/quinn/tree/timon/read-me-update I still see the bullet points in the Contribution section.

o whoops my bad. I changed the wrong bullet points I see

Ah yeah, please change those back. :)

Fixed it 👍

…reaks.

Obsolete

djc · 2020-11-05T08:45:03Z

Thanks for sticking with it, this is a good change!

TimonPost added 2 commits October 12, 2020 16:09

Add links session

2faac1e

Add PSD file, remove toml section, re-added buffer/certificate sectio…

f3e8493

…n, up-date current draft.

Remove status list; add Experimental http support to features list

5214846

Remove checkboxes

ea4bd28

TimonPost added 5 commits October 14, 2020 14:14

Merge branch 'main' into timon/read-me-update

cc65601

Change features section to be the first, then overview, then getting …

0e0a717

…started; Add Jean as colaborater/author; Change to new logo, and reduce vertical height; Add capital letter and period to overview

Add period.

84bd7ed

Add feature.

bb1b7cd

Remove book files not belonging in this PR

7472bff

TimonPost added 2 commits October 14, 2020 16:17

Add logo.

dec1feb

Increase image width

73e123f

TimonPost mentioned this pull request Oct 23, 2020

Documentation - tracking issue #861

Open

3 tasks

TimonPost added 4 commits October 23, 2020 17:56

Enter after every header; Fix autor capitalisation; Revert overview t…

6e7d2e7

…able to list; Remove periods links.

Remove book files not belonging to the project.

f368a7a

Founder instead of creator

7433edf

Add updated PSD file

a3abc7a

Add more space (same space as in the 'u') between letters and logo; A…

9c7c755

…dd more space in the circle; Ensure strike trough line is evenenly sized as space between letters; Change Q spacing;

TimonPost added 3 commits October 28, 2020 15:30

Replace thumbnail with svg

0080d8c

SVG with vectorized texst.

f3f3163

Try out other path

950e69c

Ralith previously requested changes Oct 31, 2020

View reviewed changes

TimonPost added 4 commits November 2, 2020 19:08

Paragraph break.

1fa2a43

Adjectives to lowercase

02c9b06

Merge

9e60b39

Revert wrong change; Changed list under contribtutions to paragraph b…

bb19c5b

…reaks.

djc approved these changes Nov 5, 2020

View reviewed changes

djc merged commit a2a02c7 into quinn-rs:main Nov 5, 2020

TimonPost deleted the timon/read-me-update branch November 11, 2020 09:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Readme update #866

Readme update #866

TimonPost commented Oct 12, 2020 •

edited

Loading

djc commented Oct 12, 2020

TimonPost commented Oct 12, 2020 •

edited

Loading

TimonPost commented Oct 12, 2020 •

edited

Loading

Ralith commented Oct 12, 2020 •

edited

Loading

Ralith commented Oct 12, 2020 •

edited

Loading

djc commented Oct 13, 2020

TimonPost commented Oct 13, 2020 •

edited

Loading

djc commented Oct 13, 2020

djc commented Oct 13, 2020

TimonPost commented Oct 14, 2020 •

edited

Loading

TimonPost commented Oct 16, 2020 •

edited

Loading

djc commented Oct 23, 2020

TimonPost commented Oct 23, 2020 •

edited

Loading

djc commented Oct 24, 2020

TimonPost commented Oct 24, 2020

djc commented Oct 27, 2020

Ralith left a comment

Ralith Oct 31, 2020

djc Nov 2, 2020

TimonPost Nov 3, 2020 •

edited

Loading

djc Nov 3, 2020

TimonPost Nov 3, 2020

djc Nov 3, 2020

TimonPost Nov 3, 2020

djc commented Nov 5, 2020

Readme update #866

Readme update #866

Conversation

TimonPost commented Oct 12, 2020 • edited Loading

Live version

Changes

Discussion

djc commented Oct 12, 2020

TimonPost commented Oct 12, 2020 • edited Loading

TimonPost commented Oct 12, 2020 • edited Loading

Ralith commented Oct 12, 2020 • edited Loading

Ralith commented Oct 12, 2020 • edited Loading

djc commented Oct 13, 2020

TimonPost commented Oct 13, 2020 • edited Loading

djc commented Oct 13, 2020

djc commented Oct 13, 2020

TimonPost commented Oct 14, 2020 • edited Loading

TimonPost commented Oct 16, 2020 • edited Loading

djc commented Oct 23, 2020

TimonPost commented Oct 23, 2020 • edited Loading

djc commented Oct 24, 2020

TimonPost commented Oct 24, 2020

djc commented Oct 27, 2020

Ralith left a comment

Choose a reason for hiding this comment

Ralith Oct 31, 2020

Choose a reason for hiding this comment

djc Nov 2, 2020

Choose a reason for hiding this comment

TimonPost Nov 3, 2020 • edited Loading

Choose a reason for hiding this comment

djc Nov 3, 2020

Choose a reason for hiding this comment

TimonPost Nov 3, 2020

Choose a reason for hiding this comment

djc Nov 3, 2020

Choose a reason for hiding this comment

TimonPost Nov 3, 2020

Choose a reason for hiding this comment

djc commented Nov 5, 2020

TimonPost commented Oct 12, 2020 •

edited

Loading

TimonPost commented Oct 12, 2020 •

edited

Loading

TimonPost commented Oct 12, 2020 •

edited

Loading

Ralith commented Oct 12, 2020 •

edited

Loading

Ralith commented Oct 12, 2020 •

edited

Loading

TimonPost commented Oct 13, 2020 •

edited

Loading

TimonPost commented Oct 14, 2020 •

edited

Loading

TimonPost commented Oct 16, 2020 •

edited

Loading

TimonPost commented Oct 23, 2020 •

edited

Loading

TimonPost Nov 3, 2020 •

edited

Loading