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@redhat.com> To: oVirt Infra <infra@ovirt.org>, devel <devel@ovirt.org> Message-ID: <e29c1310-e2b3-1fb9-b8c5-c550228b7732@redhat.com> 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" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEcpcqg+UmRT3yiF+BVen596wcRD8FAli4V60ACgkQVen596wc RD+/fBAAhmXiovdzodTCCOM1RYMYgWJ5LU4l3TsUovUZ2s/Hkbsfody4lOJ+XiQQ FETx3bc84UYEh3ot8WE1qkwVAc2UZI/ToN4KMQqE9GyIeAliGYdgKwSE2HO+qgJI De2jpZv7JAuSZl8MgN5sw58mhmLygvKcTTB7XdzaFzwFpEyoDoM28YgBByu7Ni9D o0A67XxZjRYhAgp9+ITzL93FYhcoQ8t9FZocqK5RhhTvOgeCSkulwQq68BLHXnAA NmoramJ0YDJa6DwEZNH0dhj/VbtJCyhUttDdHuVUgucmuyDi7X1+8nMfBb6e3Zb2 8Ua20mLrCdBlfCbj5cdH72Hz8/fzgPbzuC46cdTaXubz3BxgL8bEwDCL4jssf28v Fy1qU8OUIpZsehfksH+wqwUAnQkZdBKoluiwnsn4QABBMAGpy8AssmUDUWasJOai XmxSO5XzrkCuJuiifE7RctaHp1ViMnSj6vtleKmFvyb0OpAZdYlbfE0OSSvA/fky ssAlPRmfS6SdwHpf3+QSM3ZGSzrs/cKXoyEQ9x7xrf5Teh98tdHgSgATDrN/Bzt9 ONhWX0JPq5Co31S0pb+fWAfIlAQRz0QN9TbDQvFP8R77dDzCn9W0qFgYxso1Aaph 8WW5R2MsZsD1WIvgtkrAF49ekdx/96aJ0X0lV+TJnU6/j474puI= =pGU4 -----END PGP SIGNATURE----- --fbpbdxi90oGq1hbBHA1h5KWXPF8ktnt9J--