[almighty] CLI Documentation

[Robert Kratky]

Hi,

A couple of points from a docs perspective:

* Guide vs reference docs -- a man page is usually almost on par with the '--help' switch when judging docs. If a man page has the EXAMPLES section, then we can talk about something like a guide-like, topic-based experience.

I'm saying this because we need both -- man pages (and --help) as well as a 'guide'. The man page is for quick reference -- for users who already know the basics, who already know their way around, and they just need a reminder (what's the syntax? which switch do I use? etc.).

A 'guide' (or a set of topics) is for those who need to wrap their heads around the concepts. How does the installation process work? What are the prerequisites? Or what steps do I follow to make stuff happen? As has been mentioned, it's also for those who want to review the docs before they actually start using the product.

* The docs team would love to help wih this, but we currently have no resources for that. We've been promised more people, but no hard dates.

That said, we're ready to start gathering requirements -- if nothing else, then we can use it to plan and estimate required capacities. Depending on priorities, we can also start to think about shifting resources, so that at least basics are documented.

About docs requirements, please, either talk to me, or file issues in https://issues.jboss.org/projects/RHDEVDOCS/ (use the 'Almighty' component).

Thanks.
Robert


> Subject: [almighty] CLI Documentation
> ------------------------
> 
> From: *Thomas Mäder* <tmader at redhat.com>
> Date: Mon, Aug 15, 2016 at 8:35 AM
> To: almighty-public at redhat.com
> 
> 
> 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
> 
> ----------
> From: *Konrad Kleine* <kkleine at redhat.com>
> Date: Mon, Aug 15, 2016 at 8:42 AM
> To: Thomas Mäder <tmader at redhat.com>
> Cc: ALMighty-public <almighty-public at redhat.com>
> 
> 
> Hi Thomas,
> 
> I think that most of the CLI programs are self-explanatory in one was or
> another, yet most of them still have man pages or some form of online
> documentation.
> 
> IMHO, no matter what format the documentation would be like, it should be
> possible to learn more about the program without having it installed or
> available to play with somewhere. Makes sense?
> 
> Regards,
> Konrad
> 
> Konrad Kleine
> 
> Software Engineer
> Red Hat GmbH
> Werner-von-Siemens-Ring 15
> 85630 Grasbrunn, Germany
> 
> _______________________________________________
> almighty-public mailing list
> almighty-public at redhat.com
> https://www.redhat.com/mailman/listinfo/almighty-public
> 
> 
> ----------
> From: *Pete Muir* <pmuir at redhat.com>
> Date: Mon, Aug 15, 2016 at 8:58 AM
> To: Thomas Mäder <tmader at redhat.com>
> Cc: ALMighty-public <almighty-public at redhat.com>
> 
> 
> For REST, Swagger seems to be almost universal nowadays.
> 
> ----------
> From: *Todd Mancini* <tmancini at redhat.com>
> Date: Mon, Aug 15, 2016 at 9:08 AM
> To: Pete Muir <pmuir at redhat.com>
> Cc: ALMighty-public <almighty-public at redhat.com>, Thomas Mäder <
> tmader at redhat.com>
> 
> 
> 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.
> 
> _______________________________________________
> almighty-public mailing list
> almighty-public at redhat.com
> https://www.redhat.com/mailman/listinfo/almighty-public
> 
> 
> ----------
> From: *Leonard Dimaggio* <ldimaggi at redhat.com>
> Date: Mon, Aug 15, 2016 at 2:44 PM
> To: Konrad Kleine <kkleine at redhat.com>
> Cc: Thomas Mäder <tmader at redhat.com>, ALMighty-public <
> almighty-public at redhat.com>
> 
> 
> +1
> 
> It should be possible for users to see/read the docs without first
> installing anything.
> 
> -- Len