Pennyworth needs some polishing

[Bischoff]

Below are impressions and suggestions by a newcomer to Pennyworth. There's a bit of everything, from small typos to more generic issues.

In the hope it helps,
#1) installation

Does the installation have to be that complicated?

2) command "pennyworth list"

"Availabe VMs" => "Available VMs"
#3) command "pennyworth help"

"copy_ssh_keys" => "copy-ssh-keys" (??? not sure)
#4) explanations / workflow

I have read several times the files README.md and examples/README.md, and
I am still quite floating between Weevee definitions, ISO images, Vagrant
definitions, Vagrant boxes, VM base definition, and so on. The output of
"pennyworth list" still seems cryptic to me. I am probably stupid, but
nvertheless, there might be the need for some step-by-step tutorial, some
schema, or something else that would enable to gather the global picture.

The "Overview" and "Terminology" sections of main README fail
in that purpose IMHO. The schema on the Wiki is also too complicated.
#5) file "README.md", "Command Line" section

None of the example works.

"$pennyworth => "$ bin/pennyworth"
"--definition-dir=example_dir" => This global option has to be given first
in the command line.
"build_base" => "build-base"
"example_dir" => "<example_dir>" or "examples"
use brackets if it's replaceable,
or give a really usable directory name
"example_image" => "<example_image>" or "(???)"
Is there an example image in examples/ ?
By the way, what kind of image ? ISO ?
See section about being lost above.
"Listing availabe VMs" => " Listing available VMs"
Why isn't last example using --definitions-dir ?
"my_machine" => "<my_machine>" or "opensuse131"
#6) file "README.md", "RSpec Helper" section

"box" => "" or "opensuse131"

The command to run that specs file is not given.

The example will fail because the Vagrant directory cannot be located.
A way to setup this directory is to add:
RSpec.configure do |config|
config.vagrant_dir = "/examples/vagrant"
end
Add this tip to the README.md, or another tip that works.

Are you sure that "inject_directory" injects a file? Doesn't it inject
a directory instead?
#7) file examples/README.md

"It can be build" => "It can be built"

Examples won't work if "-d examples/" option is not put first.
#8) command "pennyworth build-base"

It really takes ages. The long-term solution is probably to move from Veewee to Kiwi.
In the meantime, could some feedback be given to show that the computer is not frozen
and still working?

[mauromorales]

Updated comment with what has been addressed or what doesn't apply any more. It's just a small start but looking forward to address as many of the improvements since I'm also a new user