I see you have directed users to look at the console help (--help) for guidance, but this isn't sufficient.
README.md (or a wiki) really needs to spend some words explaining the use of each user-facing unit.
Conscientious reviewers will definitely checkout your repo and attempt to use rhometa. If there is difficulty, you will get negative feedback. Keep in mind, people will only devote so much time when trying a new tool.
Your documentation needs demo of each worfklow and a description of options each has, particularly for those that are mandatory. It's really helpful to offer wisdom on what are sensible values, too. The less a user has to specify initially the better, so long as the options are also explained. When they develop more expertise, they can always come back to twiddle.
Looking lookup_table_gen.nf, I think you really need to provide a nice work-through. How deep is enough, etc? You can also hand them a pre-made table and lessen how critical this section of your help will be, but I would still cosndier it super important that any user that wants to know all the finer points, can learn them.
Comments on Console Help
Your CLI options are frequently long abridged phrases, akin to verbose program variables. As there is little to no context for console commands (unlike a source-code file), long names aren't that enlightening to users. Long names should really just be use when disambiguating similar options.
Using lookup_table_gen.nf as talking point
Users are likely to have no more appreciation of ldpop_rho_range vs than just rho_range or even something more directed towards what the table actually is, such as grid_spec.
In console help, I would suggest the mandatory and optional commands be tabulated separately. It makes it a lot easier for to see what's important at a glance.
The console help text is wrapping in a way that makes it difficult to read.
If specifying parameter types (eg. [str]) , think about whether that helps the user. In the case of an option that might name an output file then [filename] would be more useful. For a string which is structured, like ldpop_rho_range, then [str] isn't telling the whole story. Instead what you've said later (["num_rh,max_rh"]) is more precise and therefore helpful.
If we obey Unix syntax convention, then square brackets imply optional arguments. I would use parentheses for other situations, if really required.
The Readme
I see you have directed users to look at the console help (
--help) for guidance, but this isn't sufficient.README.md (or a wiki) really needs to spend some words explaining the use of each user-facing unit.
Conscientious reviewers will definitely checkout your repo and attempt to use
rhometa. If there is difficulty, you will get negative feedback. Keep in mind, people will only devote so much time when trying a new tool.Your documentation needs demo of each worfklow and a description of options each has, particularly for those that are mandatory. It's really helpful to offer wisdom on what are sensible values, too. The less a user has to specify initially the better, so long as the options are also explained. When they develop more expertise, they can always come back to twiddle.
Looking
lookup_table_gen.nf, I think you really need to provide a nice work-through. How deep is enough, etc? You can also hand them a pre-made table and lessen how critical this section of your help will be, but I would still cosndier it super important that any user that wants to know all the finer points, can learn them.Comments on Console Help
Your CLI options are frequently long abridged phrases, akin to verbose program variables. As there is little to no context for console commands (unlike a source-code file), long names aren't that enlightening to users. Long names should really just be use when disambiguating similar options.
Using
lookup_table_gen.nfas talking pointldpop_rho_rangevs than justrho_rangeor even something more directed towards what the table actually is, such asgrid_spec.[str]) , think about whether that helps the user. In the case of an option that might name an output file then[filename]would be more useful. For a string which is structured, likeldpop_rho_range, then[str]isn't telling the whole story. Instead what you've said later (["num_rh,max_rh"]) is more precise and therefore helpful.