wesleyleite
commented
10 years ago 1 - license added, tanks 2 - my default language is pt-br, the time is complicated, too busy, sorry. 'enhancements' 3 - I'll use the wiki for this propose. 4 - are no, has been designed to solve a problema tath i was having to test an API, but, there are still problem is incomplete. 5 - to do. 6 - Bash v4 or greater nothing more. 7 - to do. 8 - go to the wiki soon. 9 - Anyway, but i'll write.
tanks for the contribuition, i'll soon provide news, hope it helps.
fhpriamo
First of all, congratulations on the project. It took you time and you decided to open-source it, which strongly suggests that you envision it may not be useful just to you, but for other people as well. With this in mind, I have some issues to address concerning the status quo of the documentation and other "minor" things. There it goes...
tl;dr: That's a lot of prose, I put my best foot forward. Just read along the tl;dr sections to spare time.
1. So... I can do WTF I want to with this???
tl;dr: Pick a license.
I noticed your project is not explicitly licensed. I won't ramble on this, here is a great link. Please, read it:
http://blog.codinghorror.com/pick-a-license-any-license/
2. English, sir, please.
tl;dr: Be consistent; write your docs fully in English.
I am a Portuguese speaker, lucky me. If I ran into a project page written in a completely strange language and if I had no other source to run to, I'd be frustrated for sure. English is understood by most people nowadays and even people with minimal knowledge of the language can find their way around.
The details of the actual implementation of your project are into English. Your own issues are written into English. Let's be consistent.
Additionally, this liability makes your project look scoped and loose.
If it's really important to you to have a doc page in Portuguese, you can opt for a non canonical version. Maybe README.pt.md? Just don't forget to keep it in sync.
3. So... what is it about, for real?
tl;dr: Write a good, objective, project description.
It took me some time to realize what your project was really about. You can blame me in part for that, I'm not really smart.
After some time, I came down to the following (please, correct me if I'm mistaken):
4. And it comes with gum inside?
tl;dr: The niceties your tool provides are not obvious.
Okay, I got it. But I could use wget or curl for that. I could use a fancy Chrome extension for that (and the list goes on...). Why would I consider your tool?
I came down to the following appealing points:
5. How do I get it running?
tl;dr: Write installation instructions.
Remember those Windows days? NNF. Done. I'm lazy, I don't want to know it's a simple shell script. Tell me what I have to do to have it running.
6. What do I get back?
tl;dr: Include samples of return data.
What is the expected return? It'd be nice if all your command samples came with samples of the kind of data they return. It would be easy to grasp the intention and I'd sure fell more secure about it.
If you're gonna buy, you'd better check what is inside first.
7. Will it run on that?
tl;dr: Include information about compatibility and portability.
I can see it's a bash script. But what about other shells? I just got rich and bought this expensive shiny notebook (It's cool, it has an apple on it's lit), will your script run on this without any trouble? But I use Windows at work, what about that?
Include information about compatibility and portability. If it's sure to run in bash under Linux is all information you get, explicit it. All info is helpful.
8. Why is it not working?
tl;dr: Include (explicit) troubleshooting information.
Include troubleshooting information. Your chmod +x is a nice example of that. You can make it explicit by highlighting it or moving it to a dedicated troubleshooting section as needed. It's not really required in every step, nor is it integrating part of your project. There will be the ones who'll blindly type it every single time they run a script. I would.
9. How can I contribute to that?
tl;dr: List all the ways people can contribute.
Forking and pushing is not possibly the only way one can contribute. You can add contributing information for people willing to test it for you under different environments, for instance.
Since I am no shell expert, writing this is my way of contributing. Long live Open Source!