AdamBessa / Fasta2Structure

2 stars 1 forks source link

Improve README so it is convenient to use by those trying to get started with your tool #1

Closed fomightez closed 8 months ago

fomightez commented 8 months ago

Your non-standard use of images for code text in the README makes getting your tool running and learning to use your tool more difficult than it has to be and doesn't follow standard practices.
Indeed, StackOverflow's How do I ask a good question? covers the deficiencies of images in code:

DO NOT post images of code, data, error messages, etc.

If you click through to Why not upload images of code/errors when asking a question?, you'll see lot of reasons for why code provided as text is undersirable.


One Example

Example under For the FASTA input: there is an image of text you expect users to type? Just put the text like below as text that users can copy and paste.

>seq1
ATGCA
>seq2
AT-CCA

Markdown is made to handle things like this.
You'll note you can just highlight what I have provided and paste into a text file and save it and then run it. No need to type it all out again when it was text when it was written.

GitHub has nice documentation on Creating and highlighting code blocks. You can even add in syntax highlighting for various code languages.

There is a multitude of other examples in your README where users cannot just copy and paste. One other egregious case of this is the three lines that are to be used to install the dependencies on Linux.



Posting here because despite a section on the README '2. User Feedback' where it says the following there is no such active group:

"A forum will be established on Google Groups (https://groups.google.com/g/fasta2structure) to facilitate communication with users. The developer will monitor this forum and consider inquiries and suggestions for program improvement."