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

[Itamar Heim]

On 11/05/2013 02:01 AM, David Jaša wrote:
> 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
>
>
>
> _______________________________________________
> Engine-devel mailing list
> Engine-devel at ovirt.org
> http://lists.ovirt.org/mailman/listinfo/engine-devel
>

"if you build it, they will come" - create a wiki with place holders, 
and relevant folks will fill it up...

probably worth to do by sections (storage, network, virt, sla, node, ux, 
infra, integration, gluster, ppc).
and a sample of format per feature
featur name [version number available from]
feature text

(or something like that).

Thanks,
    Itamar