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