On 10/03/2014 03:23 AM, Alois Mahdal wrote:
Hi,
On Wed, 01 Oct 2014 14:29:38 +0200, Jan Safranek <jsafrane(a)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