About the doc and website

[Marc Dequènes (Duck)]

Quack,

(I'm not on devel@, so please keep me on Cc)

OVIRT-1202 raised some interesting question about doc storage and
resources. Part of it is related to a subject that was raised multiple
times and I'd like to discuss.

OSAS recently added the Gnocchi (http://gnocchi.xyz/) project to the
hosted tenants in the Community Cage, and it was interesting discussing
with the author about how they manage to have a clean documentation.

On the technical side, Gnocchi uses Sphynx, the Python doc generator,
and it seem to do a good job. They use tox to build for multiple
versions. Seem a good example. The builder and site are hosted in the
Cage and we use Ansible to deploy it. This was not a big job to get it
working and we already received contributions, so I'm very happy with
this deployment.

On the organization side, the doc is maintained along with the code, not
outside on some wiki or the like, so no feature or change is accepted
unless the corresponding doc update it done. Doc builders are in charge
of publishing the doc properly, and devs do not have to worry about it.
So the idea of splitting the project presentation and marketing from the
technical documentation seem to really make sense (currently all piled
on on http://www.ovirt.org/). Also the workflow should prevent doc from
lagging behind. Not only API doc, but guides should be part of it. As
for team planning, and technical discussions or drafts which are not yet
reality, I forgot to ask how they handle it.

I don't know well how oVirt is coded, but that's general ideas based on
successful other projects. People have been quite upset with the state
of the documentation, and we (Garret, Bkp and me mostly) fixed a lot of
broken links, lost assets… so maybe we could reboot this subject peacefully.

\_o<

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://lists.ovirt.org/pipermail/infra/attachments/20170303/5f56bea8/attachment-0001.sig>