[Engine-devel] Missing: Always up-to-date documentation of oVirt

[David Jaša]

Hi,

The oVirt project made a great progress in last two releases, who
doesn't believe, check Itamar's talk from recent KVM Forum. :) There is
a downside to that positive trend though: oVirt has become too large for
one person to know all its feautures in detail (save for full-time
managers of course).

The only sources currently are feature pages that tend to get outdated
fairly quickly after their respective feature initial implementation,
and release notes. This means that user evaluating oVirt or user looking
for particular feature has to cycle through release notes of several
versions, go through prospective feature pages or try luck with
hopefully suitable full text query.

RHEV/RHS documentation is good but not perfect either because it may
lack some feature available upstream and it also has some for latest
features.

oVirt should present itself better than now in this respect. Full-blown
documentation such as the one for RHEV/RHS is out of question IMO as it
requires steady effort of handful of people to keep it up-to date and
covered.

What IMO is feasible though is something like what libvirt does - keep
page/pages such as [1] that enumerates features with a short description
and note of version since when the feature was available. It is feasible
because the required run-time effort on single person is quite low: when
the feature is added or heavily modified, a description of similar size
to DocText of RFE bug has to be added/updated in the documentation page.

There is just one problem in getting there: agree if the problem really
exists and devote resources to record current state of affairs. There is
also one technical catch: if the documentation is to be consumable by
downstreams, the "available since" notes have to be in common format
that can be machine-converted downstream to matching d/s versions.

I personally can't do much more than spin up a discussion and probably
write about area I know, so I hope that this email can trigger actual
actions by Someone Else leading to ultimate goal....

Cheers,

David

[1] http://libvirt.org/formatdomain.html

-- 

David Jaša, RHCE

SPICE QE based in Brno
GPG Key:     22C33E24 
Fingerprint: 513A 060B D1B4 2A72 7F0D 0278 B125 CD00 22C3 3E24


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 5727 bytes
Desc: not available
URL: <http://lists.ovirt.org/pipermail/devel/attachments/20131105/5dee6f6d/attachment-0001.bin>