overhaul README prior to release

gurgeous commented 8 years ago

Here are some suggestions off the top of my head:

add "Motivation" section
add "Escaping" section, talk about cmd.execute("echo", "hello world")
buff up "Logging" (out/err and printers)
add "Errors" and discuss execute!
add "Advanced Options" to include chdir, redirects, etc.
document dryrun (if implemented) and Printers::Quiet

?

gurgeous commented 8 years ago

I can get started on this if you give me a bit of feedback...

piotrmurach commented 8 years ago

Motivation section - :+1: go for it, I think it's good to explain rational why people may want to use this thing in the first place
Escaping section - I think this one could be part of examples or subsection under 2.1 Execute?
Errors - Sure thing, I've already added some stuff about errors to 2.2 Execute! which as things stand need to be copied to appropriate section either 2.1. Execute or completely new section. Your choice!
Logging - I've stared on this section but more can be added

On general note, I think I would keep the Interface as lean as possible to explain what you can actually call and what options are possible. And then add more advanced usage examples after it.

I think it would be super helpful to get smaller PRs for review :smile:

piotrmurach commented 8 years ago

Hi Adam, how you getting on with these?

gurgeous commented 8 years ago

I wanted to do it this weekend but life intervened. Hopefully the next day or two!

On Sat, May 21, 2016 at 2:47 PM, Piotr Murach notifications@github.com wrote:

Hi Adam, how you getting on with these?

— You are receiving this because you authored the thread. Reply to this email directly or view it on GitHub https://github.com/piotrmurach/tty-command/issues/17#issuecomment-220796847

piotrmurach commented 8 years ago

I feel you, no worries, looking forward to it.

gurgeous commented 8 years ago

Personally I would divide the interface into two sections:

Interface - execute, execute! (+Result), dry_run & logging (I think these are the bits that people will be most interested in)
Advanced Interface - chdir, in/out/err, timeout, user/group/umask (also quite useful, but secondary)

What do you think?

piotrmurach commented 8 years ago

The original thought behind the content structure was dictated by the signature of the execute call, e.i. env, command, args and options. But that's probably very mechanical approach to documentation. What you've suggested has merit and I would say let's do it! I would still keep the environment variables and redirection sections but move them to advanced interface if possible.

On another note, I'm planning to release what we have the coming weekend if that's ok with you. I normally try to release as soon as there is something working and iterate, I have few things for v0.2.0 etc... but I want people to start playing with the library if we think it's good enough.

piotrmurach commented 8 years ago

After loads of deliberation I've changed execute to run, hopefully this will be more intuitive for people.

gurgeous commented 8 years ago

Great, I approve! I'll re-submit my PR using run. I'll try to get in some more doc PRs prior to release. Looking forward to it!

gurgeous commented 8 years ago

here's my TOC generator if you need it:

#!/usr/bin/env ruby

lines = File.readlines("/tmp/README.md").map(&:chomp)
toc = lines.grep(/^#+ \d/)
toc.each do |line|
  next if line !~ /^(#+)\s+([\d.]+)\s*(.*)/
  pounds, chapter, title = $1, $2, $3

  # remove trailing dot from chapter
  chapter = chapter.gsub(/\.$/, "")

  # title => anchor
  anchor = title.downcase
  anchor = anchor.gsub(/[^a-z0-9 ]/, "")
  anchor = anchor.gsub(/\s+/, "").gsub(/^ | $/, "")
  anchor = anchor.gsub(" ", "-")

  # now output
  s = ""
  s += "  " * (pounds.length - 2)
  s += "* [#{chapter}. #{title}]"
  s += "(#"
  s += chapter.gsub(".", "")
  s += "-#{anchor})"
  puts s
end

piotrmurach commented 8 years ago

Do you think the docs are good enough? Is there anything else we should consider adding/changing?

On another note, the gem ended up being mentioned on rubyweekly - cheers for all the help so far Adam!

gurgeous commented 8 years ago

Oh, I think the docs are just great for anyone looking to get started. It seems like a fine start for the gem. Nice mention on ruby weekly too, that always drives some traffic. How are you feeling about things?

piotrmurach commented 8 years ago

As with any library I feel this is a solid start but there is quite few things I would like to look into. Hopefully people will get using the lib and point out any api deficiency or new use cases. Also, once I have more time I will post ideas/issues for improvements. How about yourself, do you see room for improvements?

I'm rather excited about few tty components ideas that will incorporate some of your thoughts from using tty in the first place(going back few months). I'm currently struggling with time but should be able to produce something by the end of this month. Please allow me some time, I will ping you when I push anything to GitHub.

piotrmurach / tty-command

overhaul README prior to release #17