[almighty] CLI Documentation

[Todd Mancini]

Documentation can take two forms: reference (e.g. --help) and guide (e.g.
man). Here's a "self documented" CLI:

foo --help
foo --baz {--bar [--blatz|--quap]} filespec | --help
   baz : baz filepec except when quap
   bar : bar baz filespec as either blatz or quap
   blatz: blatz contents of filespec as baz bar
   quap: quap contents of filespec as baz bar
   help: this highly informative text


So, tell me exactly what this self-documented CLI does, and how/when/why
I'd use it?

As such, I'd take any request to 'document' any form of API (CLI, REST,
etc.)) as a request to also include at least a basic user guide.

On Mon, Aug 15, 2016 at 8:58 AM, Pete Muir <pmuir at redhat.com> wrote:

> For REST, Swagger seems to be almost universal nowadays.
>
> On 15 August 2016 at 08:35, Thomas Mäder <tmader at redhat.com> wrote:
> > Hi folks,
> >
> > It has been requested that we document our command line interface. To me,
> > however it's not quite clear in what form we should do that: technically,
> > the cli is self-documenting. If you do "alm-cli --help", it will give
> you a
> > list of possible commands and options. The alm-cli command is mentioned
> in
> > the developer set up section on github. Do we believe this is sufficient?
> > What else is necessary?
> >
> > The same question applies to the REST API
> >
> > /Thomas
> >
> > _______________________________________________
> > almighty-public mailing list
> > almighty-public at redhat.com
> > https://www.redhat.com/mailman/listinfo/almighty-public
>
> _______________________________________________
> almighty-public mailing list
> almighty-public at redhat.com
> https://www.redhat.com/mailman/listinfo/almighty-public
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/almighty-public/attachments/20160815/49169574/attachment.htm>