Are setshelliter and listshelliter documented?

[David Medinets <da...@gmail.com>]

I see these shell commands are unit tested, but is there use described in
prose?

Re: Are setshelliter and listshelliter documented?

[David Medinets <da...@gmail.com>]

The help documentation is comprehensive but not sufficient. Typically the
prose provides context about why a given command should be used instead of
another. And explains concepts like the profile name. When generating prose
and thinking about context a different point of view is achieved.
Somethings this is helpful to developers. And it's nearly always helpful to
users. This kind of writing is impossible for non-coders to accomplish
because an intimate knowledge of the code is needed. Non-coders can polish
the prose and add examples afterwards but technical people need to get the
basic concepts communicated.


On Tue, Jun 17, 2014 at 6:44 PM, Christopher <ct...@apache.org> wrote:

> The shell commands are documented in the shell itself (<command> --help) or
> (help <command>) or (<command> -?). Documentation in prose in the manual
> *might* be useful (maybe), but I think that it matters more that the
> shell's help documentation is sufficient. The manual should refer to that
> help command for details about the available commands. We don't really want
> to promote use of the shell for things other than triage/maintenance stuff,
> so there hasn't been an emphasis on it in external documentation.
>
>
> --
> Christopher L Tubbs II
> http://gravatar.com/ctubbsii
>
>
> On Sat, Jun 14, 2014 at 10:38 PM, David Medinets <david.medinets@gmail.com
> >
> wrote:
>
> > I see these shell commands are unit tested, but is there use described in
> > prose?
> >
>

Re: Are setshelliter and listshelliter documented?

[Christopher <ct...@apache.org>]

The shell commands are documented in the shell itself (<command> --help) or
(help <command>) or (<command> -?). Documentation in prose in the manual
*might* be useful (maybe), but I think that it matters more that the
shell's help documentation is sufficient. The manual should refer to that
help command for details about the available commands. We don't really want
to promote use of the shell for things other than triage/maintenance stuff,
so there hasn't been an emphasis on it in external documentation.


--
Christopher L Tubbs II
http://gravatar.com/ctubbsii


On Sat, Jun 14, 2014 at 10:38 PM, David Medinets <da...@gmail.com>
wrote:

> I see these shell commands are unit tested, but is there use described in
> prose?
>