Documentation overhaul

Jan Safranek jsafrane at redhat.com
Fri Oct 3 11:03:08 UTC 2014


On 10/03/2014 03:23 AM, Alois Mahdal wrote:
> Hi,
> 
> On Wed, 01 Oct 2014 14:29:38 +0200, Jan Safranek <jsafrane at redhat.com>
> wrote:
> 
>> I haven't got much feedback, but in the meantime I polished the chapter
>> structure, images, links and lot of tiny details in the builder script,
>> so I think it's ready for alpha release.
> 
> Sorry for lack of feedback lately.  In a nutshell:
> 
> I really like where this is going.  Currently the documentation is already
> *way* better than ever before --- mainly regarding organization, style and
> overall structure.
> 
> Kudos! :)
> 
> ~
> 
> Now for some less-than-enthusiastic part of the feedback.  Mostly it's
> small
> things and mostly I'm sure you know it, but:
> 
> 
>> Find the documentation at oopenlmi.readthedocs.org and the git repo at
>> github.com/openlmi/openlmi-doc. The re-build process is still manual,
>> i.e. I personally must tell rtd.org to fetch new docs from git and
>> regenerate everything.
> 
> <pardon_me_but><rant id="the_only_one" seasoning="bucket_of_salt">
> 
>     By the way, Is it really necessary to build the whole of everything
>     just to get the HTML files?  Note that due to json-glib 1.0 dependency
>     in openlmi-providers (-WITH-JOBMANAGER) this is currently only possible
>     in Fedora 21.
> 
>     I tried to look at the build scripts to see if there's something that
>     could be simplified or omitted, but after few minutes I got lost (it's
>     full of cryptic targets, `pwd`s and ../../../..'s) and scared so I ^D'd
>     for my life and sanity... :)
> 
> </rant></pardon_me_but>
> 
> 
>> If you want to play with it by yourself, clone the git repo and follow
>> README.md there.
> 
> Regarding README.md:
> 
>  1. gcc is missing
>  2. git is missing
>  3. if the above added, the statement about *.spec holds no more.
>  4. Something else may be missing: on Fedora 21 Alpha (Server) with
>     all above installed it still fails:
> 
>         http://fpaste.org/138732/

python-pip is missing. I'll add it to the list. The build process is
really very specific, our Makefiles differ from git repo to git repo -
e.g. build process for openlmi-tools is totally different to say
openlmi-providers. The build script is going to be quite fragile :-(.


>> Please look at all the docs and suggest improvements.
> 
> Few things:
> 
>  *  When navigating docs in-depth using left navigation menu, sometimes
>     I get impression that the fourth ("white") level in the navigation
>     menu is unnecessary.
> 
>      *  Most of the time all chapters addressed by it are short enough
>         to fit couple of screens.
> 
>      *  Also the chapters often follow in a sensible order and create
>         a logical unit so that it makes a lot of sense to read them all
>         at once (e.g. service provider -> usage covers: list, start-stop,
>         enable/disable, indications)
> 
>      *  It makes the UX of menu navigation inconsistent, since some
>         items open new page, but others only scroll to a heading.
> 
>         Here it would make sense to maintain a rule: one HTML page
>         (i.e. one GET) per leaf of the navigation tree.
> 
>      *  In general, the flatter the structure is, the better for UX.
> 

I don't like four levels either, but I was not  able to fit storage
provider docs to three levels. The same with LMI metacommand detailed
docs (OpenLMI client components » LMI metacommand » Command development)
and LMI scripts API (OpenLMI client components » OpenLMI Tools API
reference » LMI Scripts API reference). Problem with Sphinx is that you
can't say that the menu should have 3 levels except subtrees A and B,
which should have 4. It must have 4 levels everywhere.

Patches welcome (no sarcasm, really).

>   * Besides "OpenLMI Client components" and "OpenLMI Server components",
>     (actually on the first place) we should have a chapter covering
>     principles behind it all (CIM/WBEM/DMTF Profiles...).
> 
>     Ideally, user with very little knowledge about these concepts should
>     be able to get the gist of what OpenLMI can give them.  IMHO such
>     process will mean switching between playing with OpenLMI and trying
>     to understand the DMTF part.
> 
>     Now:
> 
>      *  we cannot send them to DMTF to read all the PDFs,
> 
	>      *  there is a tutorial[1] (I have found exactly one) from DMTF
> somewhere
>         but it's kind of ... short. and maybe a little obsolete (recommends
>         IE4+! for viewing)
> 
>      *  even if there was good external tutorial, nothing beats having it
>         one-click away, and even tailored to focus on those parts of the
>         concept we use in examples most (broker, namespaces...).
> 

I think these tutorials should be out of docs.openlmi.org, probably on
openlmi.org itself. The docs are for people who know what OpenLMI + WBEM
+ CIM is (we can link a tutorial from docs), but I'd like to keep it
focused on details. If you download javadoc documentation of something,
you don't find tutorials there.

>  *  Could "Class reference" and "Inheritance Tree" be merged into their
>     parent?  IIUC, Class reference does not provide anything that would not
>     be accessible from the tree (with little page search)
> 
>     Thinking about it, would it make sense to put the Class Reference on
>     top-level as well?

You are right, the list of classes is not very helpful, anyone can do
ctrl+f on the 'inheritance tree' page. I'll try to do something about it.

Jan


More information about the openlmi-devel mailing list