Documentation overhaul

Jan Safranek jsafrane at redhat.com
Wed Sep 24 15:56:53 UTC 2014


We've been busy last weeks with reworking all OpenLMI documentation.
Initially I wanted to post this announcement when the new docs are
finished, but with each version I'm finding new problems and tiny
glitches which need some attention and the finished version is further
and further ahead.

So, the work-in-progress version is available at
http://openlmi-test-doc.readthedocs.org/en/latest/.

The ultimate goal is:
- to have it generated by readthedocs.org, as it has nice style (few
tweaks were needed though and their build system is... hard to tackle with)

- to have it hosted on doc.openlmi.org, if possible

- have all documentation (providers, storage, networking, tools,
scripts) together on one place and linked together (e.g. links from
providers to appropriate lmi metacommand and back, not done yet)

- still have possibility to ship the documentation as part of our
packages (some people prefer offline docs), we'll see if we can achieve
this.

- be more newbie-friendly, especially in the overview pages (again, not
there yet, but 'Storage provider' front page is the first attempt.

- obsolete some pages on openlmi.org. We'd like all the _documentation_
to be on doc.openlmi.org, and leave openlmi.org just for overview, some
tutorials (QuickStart) and integration with other projects (Pegasus SSL
setup, IPA, ...). All text related to providers, shell or metacommand
will be removed from there, as it is inconsistent, redundant and often
completely wrong.


What's ready for review:
- overall style (colors, fonts, ...). We believe readthedocs.org has
done great job in this, I have just added support for four levels of the
navigation menu on the left

- overall structure (= the navigation menu)
  - some chapters have weird name, I know about"
    - OpenLMI Networking Provider documentation should be just
"Networking provider"
    - OpenLMI Tools documentation should be "OpenLMI client tools and
utilities" or something like that, as it covers lmi metacommand,
lmishell and OpenLMI scripts.

- most of OpenLMI providers
  - except networking
  - storage should not include "CIM classes" chapter
  - all providers need better front pages with overview, link to
appropriate lmi metacommand reference. See storage as example.

I'm tuning client utilities chapters, adding python API reference,
individual metacommand, adjusting chapter names etc.


You can see there is lot of work ahead. You can contribute, best by
patches to individual git repos (openlmi-providers, -networking,
-storage and -tools; use reviewboard as usual) or by feedback here on
openlmi-devel.

For better docs!

Jan


More information about the openlmi-devel mailing list