Problem
README.md diverges from the shape of the organisation's other public
repositories in three ways that a reader crossing between them notices.
1. No H1
The file opens with a bare image, then ## Overview. Every other public
repository here opens with an H1 naming the package. GitHub renders the repo
name above the README, so this is not fatal, but anywhere the README travels
without that chrome (a package index, a search result, a rendered copy) it
begins with no title at all.
2. No licence section
There is no ## Licence section and no statement of the licence in the README
body. The sibling repositories carry one. A reader deciding whether they can use
this package has to go looking for LICENSE rather than being told.
3. Emoji headings
Line 21 is ### 🎥 Video Demonstration, and line 24 repeats the emoji in the
link text. The house writing style for public copy does not use emoji. The
demonstration itself is worth keeping and worth the prominence, so this is about
the heading, not the content.
Suggested shape
# UIStream
<badges>
## Overview
...
## Video demonstration
...
## Licence
MIT. See [LICENSE](LICENSE).
Note the heading is also currently title-case (Video Demonstration); the house
style is sentence case, so Video demonstration fixes both in one edit.
Why bother
Individually each of these is cosmetic. Together they are the difference between
the public repositories reading as one organisation and reading as three
unrelated projects that happen to share an owner. This repository is the one a
crossing reader currently judges hardest, which is the only reason it is worth a
ticket rather than a passing note.
Problem
README.mddiverges from the shape of the organisation's other publicrepositories in three ways that a reader crossing between them notices.
1. No H1
The file opens with a bare image, then
## Overview. Every other publicrepository here opens with an H1 naming the package. GitHub renders the repo
name above the README, so this is not fatal, but anywhere the README travels
without that chrome (a package index, a search result, a rendered copy) it
begins with no title at all.
2. No licence section
There is no
## Licencesection and no statement of the licence in the READMEbody. The sibling repositories carry one. A reader deciding whether they can use
this package has to go looking for
LICENSErather than being told.3. Emoji headings
Line 21 is
### 🎥 Video Demonstration, and line 24 repeats the emoji in thelink text. The house writing style for public copy does not use emoji. The
demonstration itself is worth keeping and worth the prominence, so this is about
the heading, not the content.
Suggested shape
Note the heading is also currently title-case (
Video Demonstration); the housestyle is sentence case, so
Video demonstrationfixes both in one edit.Why bother
Individually each of these is cosmetic. Together they are the difference between
the public repositories reading as one organisation and reading as three
unrelated projects that happen to share an owner. This repository is the one a
crossing reader currently judges hardest, which is the only reason it is worth a
ticket rather than a passing note.