README doesn't explain what gren does

[broofa]

Installed gren, created github key, ran gren, no errors... but nothing seems to have happened?

gren --help yields nothing useful.

What exactly is the expected result of all this? README seems to miss the mark in terms of explaining what this (hopefully useful) tool does, I'm afraid.

FWIW, my console output:

---

kieffer@MacBook-Pro-3$ pwd
/Users/kieffer/projects/node-mime

kieffer@MacBook-Pro-3$ lsf
total 80
-rw-r--r--   1 kieffer  staff  1098 May 11 21:53 LICENSE
-rw-r--r--   1 kieffer  staff  1894 Sep 12 15:32 Mime.js
-rw-r--r--   1 kieffer  staff  5053 Sep 12 15:40 README.md
-rw-r--r--   1 kieffer  staff   150 Sep 12 15:32 cli.js
-rw-r--r--   1 kieffer  staff   114 Sep 12 15:32 index.js
-rw-r--r--   1 kieffer  staff    88 Sep 12 15:32 lite.js
drwxr-xr-x  35 kieffer  staff  1190 Sep 12 15:44 node_modules/
-rw-r--r--   1 kieffer  staff  8168 Sep 12 15:44 package-lock.json
-rw-r--r--   1 kieffer  staff   962 Sep 12 15:44 package.json
drwxr-xr-x   6 kieffer  staff   204 Sep 12 15:40 src/
drwxr-xr-x   4 kieffer  staff   136 Sep 12 15:32 types/

kieffer@MacBook-Pro-3$ gren

Release task:
===================================
Getting the list of releases: ..... (0.49 secs)
1 releases found
Getting tags: .... (0.33 secs)
Tags found: v1.4.0, v1.3.6
Getting the tag dates ranges: .... (0.34 secs)
Creating the body blocks from releases:
Getting all closed issues: ...... (0.52 secs)
13 issues found
Skipping v1.4.0 (use --override to replace it)

kieffer@MacBook-Pro-3$ lsf
total 80
-rw-r--r--   1 kieffer  staff  1098 May 11 21:53 LICENSE
-rw-r--r--   1 kieffer  staff  1894 Sep 12 15:32 Mime.js
-rw-r--r--   1 kieffer  staff  5053 Sep 12 15:40 README.md
-rw-r--r--   1 kieffer  staff   150 Sep 12 15:32 cli.js
-rw-r--r--   1 kieffer  staff   114 Sep 12 15:32 index.js
-rw-r--r--   1 kieffer  staff    88 Sep 12 15:32 lite.js
drwxr-xr-x  35 kieffer  staff  1190 Sep 12 15:44 node_modules/
-rw-r--r--   1 kieffer  staff  8168 Sep 12 15:44 package-lock.json
-rw-r--r--   1 kieffer  staff   962 Sep 12 15:44 package.json
drwxr-xr-x   6 kieffer  staff   204 Sep 12 15:40 src/
drwxr-xr-x   4 kieffer  staff   136 Sep 12 15:32 types/

kieffer@MacBook-Pro-3$

[broofa]

Found https://github-tools.github.io/github-release-notes/examples after a bit of hunting around.

1. The way the action param is documented could be clearer. IMHO, the first thing in the readme should be a Usage section with gren [--action=[release|changelog] ... style notation. Then document each param, what it does, and provide an example below that. (My $.02)

2. The animated gifs aren't very helpful. Would prefer simple copy/paste of console log for examples. Easier to follow.

[Edit: Part of the problem with the gifs is that you only see the last few lines of output - the most interesting part, generally - for a split second before it starts over. Frustrating.]

Other than that, thanks for a cool tool!

[broofa]

Oh... and look, apparently gren documented the release under my project's "releases" tab. That's really cool... yet not at all obvious that's what's happening. (And, yes, maybe I should have surmised this was what was going to happen based on the name, but I was expecting it to generate a RELEASE_NOTES.md file or something like that.)

[dddom]

I suppose it's worth mentioning I think it’d be great if the first thing you read was about the philosophy of this tool, that it’s GITHUB RELEASE NOTES, how you should use GitHub to create the right content for this tool to use, what would be the steps or workflow, philosophy I’d need to adapt to be able to use this tool effectively, what benefits would that bring etc.

@broofa has a point about the gifs, I don’t find them useful either, because it’s not useful to see the process of printing the log and have it disappear immediately. Console output would be better in this case, if not even just concise screenshots (syntax highlighting is useful).

[alexcanessa]

@broofa, @dddom good points.

I always had the impression that either the README.md or the documentation, in general, were clear enough.

Thanks for your feedback, definitely going to address it.

[broofa]

If I had a nickel for every time I thought my docs were obvious, only to be proven horribly wrong... :-)

Thanks for your patience with this noob.

[alexcanessa]

@broofa the new README.md and documentation should fix this issue.

Closed by #85