[ovirt-devel] [ovirt-users] Lowering the bar for wiki contribution?

[Marc Dequènes (Duck)]

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/…

> 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 contribute.



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… 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…
patches are welcome!

\_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/20170622/8c9ec1d3/attachment.sig>