[improve] doc & help <command>

[wollmers]

Just a first impression as a fresh user:

• The main pod gives priority to installation. Should be more init and usage without scroll down.

• Provide a help command like many other command line utilities (e.g. git, milla) in a standard way

tracker help <command>

• Similar for calling tracker without command or option: provide a short usage information with version and syntax.

I could do this and a little bit more usability improvements, but not this week.

[paultcochrane]

Where do you think the installation information would be better located? As a new user, I usually want to get the thing installed before I can get going with initialisation and setup, hence for me having the installation docs at the top is very helpful. Perhaps the installation docs should be attached directly to App::TimeTracker rather than to the tracker command. What do you think? Would that improve the workflow for new users?

There is a help command; the syntax for the individual commands is only slightly different to that for e.g. git. For instance:

tracker help

shows the available commands and

tracker <command> --help

shows the available options for the given command. This is also a fairly standard pattern. (AFAICT, the help text is automatically generated from the documentation attribute via Moose::Meta::Attribute).

Calling tracker on its own currently shows the available commands, however I think you're right: this should probably provide short usage information. Let's see what @domm has to say :-)

[wollmers]

@paultcochrane Yes, I also think, that App::TimeTracker is the best place for the overview (install, init, configure) and links/references to details. As a user I would expect usage information in man tracker or perldoc tracker. No installation advice needed there, because successful installation is a precondition to use it.

E. g. Dist::Milla provides both forms of help (command and option):

$ milla
milla <command> [-?hIVv] [long options...]
	-v --verbose                         log additional output
	-V STR... --verbose-plugin STR...    log additional output from some
	                                     plugins only
	-I STR... --lib-inc STR...           additional @INC dirs
	-? -h --help                         show help

Available commands:

    commands: list the application's commands
        help: display a command's help screen

         add: add modules to an existing dist
  authordeps: list your distribution's author dependencies
       build: build your dist
       clean: clean up after build, test, or install
     install: install your dist
    listdeps: print your distribution's prerequisites
         new: mint a new dist
         nop: do nothing: initialize dzil, then exit
     release: release your dist
         run: run stuff in a dir where your dist is built
       setup: set up a basic global config file
       smoke: smoke your dist
        test: test your dist

The reason for submitting this issue is, that I first missed to init and then wanted to add a comment to start. Then got back to the source and found details in App::TimeTracker::Command::Core.

And how should I know, that a help command exists? It's not documented in App::TimeTracker::Command::Core.

[paultcochrane]

@paultcochrane Yes, I also think, that App::TimeTracker is the best place for the overview (install, init, configure) and links/references to details. As a user I would expect usage information in man tracker or perldoc tracker. No installation advice needed there, because successful installation is a precondition to use it.

Good point. I'll see if I can rustle up a PR or two to improve the situation.

E. g. Dist::Milla provides both forms of help (command and option):

Definitely something to look into more closely. I can feel more PRs coming on ... ;-)

The reason for submitting this issue is, that I first missed to init and then wanted to add a comment to start. Then got back to the source and found details in App::TimeTracker::Command::Core.

Yeah, that shouldn't be the way a user should find out about a feature.

And how should I know, that a help command exists? It's not documented in App::TimeTracker::Command::Core.

Good point.

Thanks for highlighting these issues! I'll see if I can get some time this week to submit a couple of patches.

[paultcochrane]

I've pushed a PR (#46) which moves the documentation around a bit so that the usage-related information is in the tracker program and the installation and more general information is documented within the main module documentation. Let me know if this fixes the first issue you raise with the documentation; the second issue (related to the help command and its output) is still to come.

[domm]

pauls work has now been merged, a new version is it's way to CPAN

[wollmers]

Thx, will try the new version ASAP.