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