[ovirt-devel] About the doc and website

This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --fbpbdxi90oGq1hbBHA1h5KWXPF8ktnt9J Content-Type: multipart/mixed; boundary="TDtgiSKijbDUNALA708IX3iruKjpKiAlG"; protected-headers="v1" From: =?UTF-8?B?TWFyYyBEZXF1w6huZXMgKER1Y2sp?= <duck(a)redhat.com&gt; To: oVirt Infra <infra(a)ovirt.org&gt;, devel <devel(a)ovirt.org&gt; Message-ID: <e29c1310-e2b3-1fb9-b8c5-c550228b7732(a)redhat.com&gt; Subject: About the doc and website --TDtgiSKijbDUNALA708IX3iruKjpKiAlG Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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=E2=80=A6 so maybe we could reboot this subject = peacefully. \_o< --TDtgiSKijbDUNALA708IX3iruKjpKiAlG-- --fbpbdxi90oGq1hbBHA1h5KWXPF8ktnt9J Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" --fbpbdxi90oGq1hbBHA1h5KWXPF8ktnt9J--