Comments on OpenLMI documentation overhaul

Peter Hatina phatina at redhat.com
Wed Oct 8 09:14:28 UTC 2014


On 10/01/2014 06:02 PM, Russell Doty wrote:
> First of all, I'm extremely impressed with the documentation overhaul! I
> apologize for not responding sooner; as a feeble excuse I was on PTO
> last week.
> 
> These comments cover LMIShell and LMI Metacommand. I will look at the
> other sections later.
> 
> Notes on LMIShell
> 
> * http://docs.openlmi.org/en/latest/openlmi-tools/shell/classes.html
> 
> "Each class in LMIShell represents a class provided by a CIMOM" - I
> think of the class as being implemented in a Provider and accessed
> through the CIMOM. The CIMOM is basically an access method to get to
> Providers.
> 
> Under Synchronous Methods should we mention that most methods we have
> implemented are asynchronous, and that you can launch them and then do
> other things while waiting for the method to finish? Perhaps add a
> section on this before the Synchronous Methods section?

OK.

> 
> 
> *
> http://docs.openlmi.org/en/latest/openlmi-tools/shell/associated_objects.html
> 
> Would it be worthwhile having a brief discussion of what associations
> are and how you use them to navigate the CIM object model?

OK.

> 
> * http://docs.openlmi.org/en/latest/openlmi-tools/shell/indications.html
> 
> We should mention that an Indicator is an event or alert that signals a
> change on the managed system. Explain that an Indication is produced by
> a Provider and received by a Listener or indication handler. Mention
> that indications are built into Providers and that you can find them in
> the Provider documentation.

OK. Will do so.

> 
> General notes:
> 
> It would be nice to mention the standard scripts - what they are
> intended for and where they live. Perhaps choose one as an example and
> show how to use it and describe the various sections. Mention that these
> scripts represent examples of recommended best practices for LMIShell
> scripts. Mention that these scripts are also intended to be copied and
> modified for specific purposes.

I am not sure about this. Isn't the mentioned text already present in
LMI metacommand doc?

> 
> 
> Notes on LMI Metacommand
> 
> Should this chapter come before the LMIShell chapter? LMI Metacommands
> are likely to be the entry point into OpenLMI for most sysadmins.
> 
> *
> http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/logicalfile/cmdline.html
> 
> We should mention that goals of the file command. Specifically, that it
> is not intended to be a general purpose file manipulation command, and
> that it does not have the ability to create, delete, or copy individual
> files.
> 
> *
> http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/powermanagement/cmdline.html
> 
> Note that the lmi power command is running inside the OS of the managed
> system. Thus, it does not have the ability to power-on a system.
> Power-on can be done manually or by accessing a BMC or managed power
> switch. Power-on is currently out of scope for OpenLMI and the LMI
> metacommand.
> 
> *
> http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/realmd/cmdline.html
> 
> Unlike the previous commands, realmd isn't available by default. Mention
> what needs to be done to install realmd and the realmd metacommand.
> 
> *
> http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/service/cmdline.html
> 
> Should we mention it when we expect a command to take a significant
> amount of time to complete? Something like "It may take 30-60 seconds to
> return a list of all available services."
> 
> *
> http://docs.openlmi.org/en/latest/openlmi-tools/scripts/commands/software/cmdline.html
> 
> Mention that the software metacommand is built on yum and that some
> operations may be slow. Notably, that a "lmi software list" of all
> software packages may require over five minutes to return a list of
> several thousand packages. We recommend using targeted searches instead
> of full lists. Provide some examples of searching for packages. 
> 
> The SHOW and LIST commands are documented; should the SEARCH command
> also be documented? It looks like you need to use SEARCH to get lists of
> packages (like openlmi) and then use the LIST and SHOW commands. It
> would be helpful to have some examples for how to use the SW
> metacommand. I found it a bit confusing that you need to use "sw list
> files openlmi-realmd" but "sw show pkg openlmi-realmd".
> 
> 
> SSSD Command
> 
> Mention that SSSD is optional and must be installed before the
> metacommand can be used.
> 
> 
> STORAGE Command
> 
> It would be helpful to start out by identifying the commands that
> provide information on storage vs. those that can modify storage. The
> storage list, show, and tree commands display information. These are
> likely to be the starting point for using the storage command.
> 
> Under LUKS mention that this is the encrypted file system.
> 
> Under THINLV and THINPOOL mention what thin provisioning is and how it
> is used.
> 
> 
> COMMAND DEVELOPMENT
> 
> *
> http://docs.openlmi.org/en/latest/openlmi-tools/scripts/development.html
> 
> Is there an easy way to get the descriptions in the Term/Description
> table to line wrap?
> 
> This section is excellent - something I've been looking for! I need to
> spend some quality time with it before providing comments.
> 
> _______________________________________________
> openlmi-devel mailing list
> openlmi-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/openlmi-devel
> 


-- 
Peter Hatina
ENG Server Experience, System Management

PGP:            F32822A9
Red Hat, Inc.   http://cz.redhat.com


More information about the openlmi-devel mailing list