Comment by dguo | Hacker News Reader

Comment by dguo | Hacker News Reader

Parent Full thread

In the specific example given here of "dbconnect", I'd consider a different approach: incorporating the "how" knowledge into the CLI itself. For example, running the command without any arguments could trigger an interactive guide that asks the user questions.

"What do you want to do?"

o Get a list of databases

o Connect to a database

"Do you want to connect to dev or prod?"

o dev

o prod

o I don't know (this option could link the user to documentation on the different environments; maybe the user is a student on his or her first internship and has never even heard of the concept)

"What's the shard number?"

"Which side?"

The CLI could output the equivalent, non-interactive command before performing the requested action, making it a teaching opportunity as well. Maybe the "I don't know" option or this approach in general is overkill, but I generally think tools should be smarter. You don't need as much documentation if your tools are inherently capable of guiding you to the right answer.

That's quite a bit more work than adding a reacmoji to 100 chars which were typed into Slack anyway. We all want better tools with fantastically helpful interfaces, but we also want functioning MVPs yesterday. I like the Etsy approach because it fits into our existing JIT dev/doc workflow.

1. I'd use a library or framework that handles the interactive parts, which should make it fast to implement. We have tools to help make other tools.

2. A tool's popularity/usage could be a way to judge when it's worth the effort to add this sort of system.

3. With the Etsy approach, I would also be wary of the cost of interruptions. Getting constant Slack notifications is not conducive to getting work done. You could silence them, but then what if someone can't move forward without getting an answer to their question?

4. There is a nice balance to be found between wasting time documenting everything possible upfront and not documenting anything until someone asks a question.

5. Personally, when I find documentation that needs to be updated, it's usually as simple as editing a wiki or editing Markdown and making a pull request in GitHub's interface. To me, that's not much effort.

Seems like a lot of overhead and more things to maintain. On top of that it doesn't teach people how to use the tool. Kinda like 600 hours of coding saved me 30 hours of documentation.

I did mention that it could output the equivalent command to teach the user what they can run in the future to bypass the interactive prompt.

Point taken, but I don't think it should take that much effort to implement. Some CLI frameworks already have built-in methods for interactivity.

Reply on news.ycombinator.com