search

block / goose

Goose is a developer agent that operates from your command line to help you do the boring stuff.
https://block.github.io/goose/
Apache License 2.0
108 stars 17 forks source link

docs: reworks README to be outcome based #151

Open codefromthecrypt opened 1 week ago

codefromthecrypt commented 1 week ago

note this is a shared branch intentionally for collaboration

This is a stab to make the intro more outcome based. I originally wanted less total words, maybe it is about the same. However, I like focusing on what goose does for me vs what goose can do in abstract. Feel free to revise.

michaelneale commented 1 week ago

@lily-de I think could add back in the wording for calling commands, but probably not the python bit as that may confuse people that this is python specific

michaelneale commented 1 week ago

@lily-de actually I think it reads the same - it is still in there?

lily-de commented 5 days ago

Here's my take, but I am not like, convinced of this or that there's a "right" answer :D

What I like about this rework is that it starts with everyday scenarios that many developers will find familiar, which can immediately engage the reader by reflecting their daily challenges and it use of questions can spark the reader's imagination about how the tool can fit into and improve their workflow -- it makes it relatable and has engaging questions.

I think the weaknesses are:

  1. The introduction could be streamlined. It's a bit lengthy and takes a while to get to the point about what Goose actually does. Tightening this up could help maintain the reader's attention. I think that is something the current version does a little bit better -- Gets to the point quickly, clearly explaining what Goose is and what it does.
  2. It lacks immediate clarity on the technical capabilities or unique features of Goose -- a new reader might need more concrete details earlier to understand its value

Overall, I still prefer the current version but it lacks a bit of the human touch that can make open-source projects more appealing. A touch of narrative or user-centric focus could make it more engaging, without being overly fluffy.

We also don't need to say Python functions, but noting that Goose allows you to create custom tools for it to use is a powerful feature worth highlighting I think? Right now it says "shell command, Python or a plugin" but I don't think that's super clear (and also is not totally accurate as plugins are defined in Python so they're not truly separate things in my view).