Restructure and improve README #90
Conversation
- Separate into sections and add a TOC at the beginning
- Add new sections for Install, Tests and License
- Add paragraph to Usage emphasizing on recommended program structuring using a single loop instance
* Separate into sections and add a TOC at the beginning * Add new sections for Install, Tests and License * Add paragraph to Usage emphasizing on recommended program structuring using a single loop instance
README.md
Outdated
| In order for async based libraries to be interoperable, they need to use the | ||
| same event loop. This component provides a common `LoopInterface` that any | ||
| library can target. This allows them to be used in the same loop, with one | ||
| single `run()` call that is controlled by the user. |
There was a problem hiding this comment.
Should this paragraph stay at the top, right below the tag line?
There was a problem hiding this comment.
Yeah, i was unsure either and moved the paragraph up and down several times while working on the patch 😃
In the end i decided to put it under Usage because i thought it fits there and might be easily overlooked at the beginning. My guess is, that users skip the "promotion" parts at just jump straight to the usage section.
But i'd be fine with both locations. @WyriHaximus, @cboden?
There was a problem hiding this comment.
The initial paragraph should try to sell this idea to newcomers and explain the WHY. This is also what will be shown as an "abstract" in many applications, e.g. the first paragraph will be shown in mobile view, while the rest will be hidden by default.
IMHO the why is the most important part of the documentation, but we may as well duplicate this below if this makes sense. Otherwise, we may also fine-tune this later on 👍
There was a problem hiding this comment.
I've moved the paragraph back to the top and replaced it here with a short introduction.