Improve Readme - Githubissues

Center-for-Research-Libraries / crl-serials-validator

Validate bibliographic and holdings data for shared print.

GNU General Public License v3.0

0 stars 1 forks source link

Improve Readme #10

Open ryan-jacobs opened 3 years ago

ryan-jacobs commented 3 years ago

The draft readme is looking great in terms of outlining dependencies and installation considerations. I think this is also a place where we'll want to put some non-technical info about the project (what it is, what it does, why it's useful, etc.). Some notes on that here: https://thoughtbot.com/blog/how-to-write-a-great-readme

There are also lots of interesting resources here on README writing:

https://github.com/matiassingers/awesome-readme

The examples are a bit over the top stylistically IMO, but the "Articles" and "Tools" sections have some good links. I'm digesting a few myself.

We may also want to target a more descripteive name... as I suspect there may be other "validator" tools that CRL will want to share down the line :)

KimSarabia commented 3 years ago

README.md Suggestions

Quick Start could be placed higher on top and the About can be condensed and in more "laymans terms" that focuses more on who it can help and what problem it solves
Another paragraph can be more technical and focus on functionality and the expected results as well as the sample input and output
Link to a sample file (in the line where you mention input folder).
Speaking of, there’s no input folder. Is this something we have to make?
To-Do: Validate on macOS

CRLTechSvcs commented 3 years ago

There is a typo in the first paragraph/sentence. ...PAPR project at CRL It howver...

ryan-jacobs commented 3 years ago

It would be helpful to have some sort of long-term vision spelled out somewhere for the project as well, perhaps in a section right between "About" and "Basic Requirements". This could be a space to let people know that this tool is currently available for use and contributions by an audience comfortable working with Python scripts, but that CRL plan to explore ways to make this same functionality available for other less-technical audience as well in the future.

nflorin commented 3 years ago

The readme is somewhat punchier, with a bit more of a focus of what the validator can do at the top, and a lot of the more verbose instructions removed or cut down.