The README in bartiq is a mini version of docs/index.md with some notable absences. Ultimately this is a duplication of text and work and could be avoided, by e.g. building the README from existing MD files within docs.
The reason I think this requires a refactor is because we do not want the README to simply be the landing page of the docs (docs/index.md) however we also do not want the same text (or ostensibly the same text) to exist in two distinct locations as these will inevitably diverge and it will look bad.
Proposed solution would be to break index.md into a number of small md files, such that both the current index.md and the README can be constructed from those new markdown files. The result would be that a single change would update both the docs and the README, and the README is no longer standalone but fully in line with the documentation.
The
READMEinbartiqis a mini version ofdocs/index.mdwith some notable absences. Ultimately this is a duplication of text and work and could be avoided, by e.g. building the README from existing MD files within docs.The reason I think this requires a refactor is because we do not want the README to simply be the landing page of the docs (
docs/index.md) however we also do not want the same text (or ostensibly the same text) to exist in two distinct locations as these will inevitably diverge and it will look bad.Proposed solution would be to break
index.mdinto a number of small md files, such that both the currentindex.mdand the README can be constructed from those new markdown files. The result would be that a single change would update both the docs and the README, and the README is no longer standalone but fully in line with the documentation.