Block-quote advisory text, to help delineate what's actually supposed

usnistgov / opensource-repo

This repository is the recommended template repository for NIST opensource contributions.

Other

6 stars 4 forks source link

Block-quote advisory text, to help delineate what's actually supposed #16

Closed tkphd closed 2 years ago

tkphd commented 2 years ago

to be edited and what should simply be cut.

Closes #14, which was hopefully also addressed by #13?

ajnelson-nist commented 2 years ago

It looks like the block-quoting assumes very long text lines are used, instead of source text being constrained to a column count. See the "Guide to Writing README-style Metadata" link, whose markdown syntax was split across two lines and then broken by the > syntax.

ajnelson-nist commented 2 years ago

As a user of this repository, I'm a bit more confused on seeing the block-quoting effect. What I'm visualizing is here (this link will break after the branch is deleted: https://github.com/usnistgov/opensource-repo/tree/issue14-the-readme-documents-contact-information-twice

What I'm looking for as an end user is:

What README sections are being prescribed and/or required by this repository.
How should those README sections be formatted.

wd15 commented 2 years ago

Trevor: I think I'm with Alex on this. I'm not sure the block quoting really works. The README.md is not a template in and of itself. It's a description of why this repository exists and isn't intended to be a template. We might want to give some links to really nice examples of READMEs (e.g this and this). The entire things needs to rewritten for a new project anyway.

tkphd commented 2 years ago

Thanks for the feedback, it's useful. I've reverted the blockquote, and rephrased some of the description. Please take another look.