This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --dqmIdtmeTimHDutWnSDmr5D33QGGuG2B8 Content-Type: multipart/mixed; boundary="EIXwtTdtuMoAf8JSMXfSSajJpI94AutSD"; protected-headers="v1" From: =?UTF-8?B?TWFyYyBEZXF1w6huZXMgKER1Y2sp?= <duck@redhat.com> To: Martin Sivak <msivak@redhat.com>, Nir Soffer <nsoffer@redhat.com> Cc: Edward Haas <edwardh@redhat.com>, devel <devel@ovirt.org>, infra <infra@ovirt.org>, users <users@ovirt.org> Message-ID: <24cf31c6-0b1e-cf4c-6843-d44f63b5d4e4@redhat.com> Subject: Re: [ovirt-devel] [ovirt-users] Lowering the bar for wiki contribution? References: <CAC_JqcnVfGeFm+xQmZU-QEbp57efphO3jhPw5rDqux7d0DCu9A@mail.gmail.com> <CAP84NrtLshq30DJPmJ6==p2DThWokKqBetKpmhKFp+r-E2CVpw@mail.gmail.com> <CAJ1JNOcxk-=Aodrc0gM7hdJi-N0nyn+vwTkbjyTEKMZNGZXZ3A@mail.gmail.com> <CAC_Jqcnkqo3sGyBqc61zo7qN61ua0ZM1f1oTPkXHcH=L2_-HQg@mail.gmail.com> <CAJVw3Ezs9bSn=OLyLRfkz=twJNn1LuzdAjbV0qTyvAcVS+KF2w@mail.gmail.com> <CAC_Jqcku_hmpF25n4Ekrdsq4SzXRWsc0jGxbSeOyao3Snie4WQ@mail.gmail.com> <CAGJrMmqKJAycawV91RDxGF5ERB3snt6s9PNtfjCPmsRO4619qA@mail.gmail.com> <6e6f7b97-9d8d-1759-5dab-c64bba86de35@redhat.com> <CAC_Jqcn6-OUKKDz2B=SF_aqwys9qrSQ+Zdhi5H8=8F_4De5Egg@mail.gmail.com> <F6E943F2-E8A2-43A1-8EF0-F08EEC60A2D5@redhat.com> <CALmkdFQM4XgtQ+opmBD9WiRQhv1puoOEj_Vn9dfS9OeSqrnyFQ@mail.gmail.com> <CAF0zDV60iZZQFnbuPwCUzSGnvFY8xn1pCtq46d982xYvU_UaUw@mail.gmail.com> <CAMRbyysJLOtWKXFX93zyyEcrDFaq+S=7x9Ek4GT3VXr-+zcjug@mail.gmail.com> <CAF0zDV4RsA5ux3KOW2Tg+ZGWXR_3fhpVfWLKsnF1oryZ0F=PbQ@mail.gmail.com> In-Reply-To: <CAF0zDV4RsA5ux3KOW2Tg+ZGWXR_3fhpVfWLKsnF1oryZ0F=PbQ@mail.gmail.com> --EIXwtTdtuMoAf8JSMXfSSajJpI94AutSD Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Quack, On 06/21/2017 05:29 PM, Martin Sivak wrote:
I think we need a wiki for this, instead of reinventing one :-)
Well, the only feature which seem to be missing (at least for some people) is to comment alongside the pages, but you can still make reviews in PRs. I think these last few month there is more people around and it is more reactive, and there's much less lingering PRs. Also I have no idea about how promoting people to merge power is done. I think there is quite an unfair side of the story: if you're from RH then you can get admin rights on the spot but external contributors I guess don't guess this very easily. I didn't any procedure to apply for this.
Other big ans successful [1] (single component) projects have docs/ directory and documentation and design reviews are integral part of code review. That way you can atomically reject/accept changes to code and docs together. We can't easily do it this way as we have multiple cooperating components, but we should try to get close.
That's a very good point. A colleague working on OpenStack stuff was telling me this works much better to commit doc alongside doc in the same PR. Also the project promotion and technical docs would probably benefit from being separated, so that giving permissions to people would not affect the main portal and messaging if they just need to write on features/config/install/=E2=80=A6
Yes we do, but we do not have commit rights. And internal technical documentation and _design_ pages need to be a bit closer to the source otherwise nobody will want to touch them.
Same.
And don't let me started on the theoretical open aspect of our project.. do we want more contributors or not? Can we afford artificial barriers? Is somebody from general public allowed to contribute ideas?
With GH and Gerrit using external auth I think anyone is able to contribu= te. So to come back to Markdown stuff. People in charge of messaging do not want an ugly portal, and even a simple one means a little bit of CSS. Also there are news/blog entries, so another feature which needs slightly more power. Also search is a nice feature too. So we're using Middleman, that's not perfect at all, version 3 is a failure, and we were looking at a new tool, Jekyll, and it's being tested on another project. Jekyll is the tool developed by GH and this rejoins Edward's proposal. Nevertheless I totally disagree about going to the bare minimum. If you want to get a clean, readable and coherent documentation you will still end-up having a few editorial rules, templates=E2=80=A6 to follow and yes= you need to get up to it and learn. With content of this size if anyone just decide to have his own flavor it will be a mess very soon. Also we already have piles of content so this means some work to migrate. Markdown is not a standard so depending on the generator you use the syntax may differ slightly. There's some custom Ruby code we need to get rid of too. So that's a real project and unfortunately the person who was working in this direction is no more in the project. Once I'm more acquainted to Jekyll and i still think this could be a nice replacement, then I'll try to get some time to help on this front. Anyway to get out of the current system we first need to remove all the custom Ruby code around Middleman and maybe other ugly things, so=E2=80=A6= patches are welcome! \_o< --EIXwtTdtuMoAf8JSMXfSSajJpI94AutSD-- --dqmIdtmeTimHDutWnSDmr5D33QGGuG2B8 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEcpcqg+UmRT3yiF+BVen596wcRD8FAllLSLgACgkQVen596wc RD8kVRAAu48DNfFeNWgMp8SFfA4SCEWuzy04/R3xmPtWYVIswVvNnWNhWfSR39Oe NHvjzkvW321csVt3ARMv7Jx1ryUVR/0VC589OSc5YuA6XK7sc+UBT6A5TywSVu2+ jvapplGy/5J8I2Bs+GefNQ5mfwCsb6DAxi/9A8uQWI0DaRifZPs9KqCHNSDxaOnk cXJK17ZgYTDsO1VkIUbyxDi3jXnQMkUGwEvcle1eVuPI0twhp4zmaflb2mis3jTD kka2s6BLDJ3aWwpANqF/joNhSXw7rH1ZiM8uOkISVoA6YWF7hhdudcSDvp54vzMQ BY48rJ4qnrGEYsG5XXxMVVIyJI7eixqkxgSqt4pvj5LSjD8E2NgrkFoPy86AoGlP f/4srL4uSP62d8pshP5FaHvi5cyOoBu2rWp9eh19AXM/dJ5T/Dhdg/eVMKb7jZwp ljWlgKh1e+mStuc0Cr/nrlqVMtAxOh17aakfEN3wCTlOle+/8JY0gR9sB84KEy8d j12HkfbjW+C5Qhsi5lT8i/b/i9IwRI63iRleHoc8Pf6Yq+1wrlr1uCeBe+2nM2At gixeEqZer/LUBhtkYUI/r5VzfatYTJ6ucI0SPI2sT8a28q5su5xWrbu2pSLcezID 9huztK1vhJ1d/UM6/+33pgqe1I5yEGUyPoL7DevJd+JQ3mVEd2Q= =PuvT -----END PGP SIGNATURE----- --dqmIdtmeTimHDutWnSDmr5D33QGGuG2B8--