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

Wed Jun 21 08:29:42 UTC 2017

> I think we need a wiki for this, instead of reinventing one :-)

Really? And ending in the same mess we had before? No thanks.

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.

> We have a builtin markdown based wiki in the ovirt site github project.

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.

> For discussion, we have the mailing list and other channels like bluejeans
> and irc.

For informal yes. But formal proposals and final design documentation
are something different.

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?

Gerrit / Github give everybody the power to easily see all currently
considered (open) projects and review them using the same interface we
use for our daily work! This way any team can catch conceptual issues
with other teams' projects. Searching through email threads is nowhere
near the same experience.

[1] kubernetes and Linux kernel just to name two

--
Martin Sivak
SLA / oVirt

On Tue, Jun 20, 2017 at 9:22 PM, Nir Soffer <nsoffer at redhat.com> wrote:
>
> בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak ‏<msivak at redhat.com>:
>>
>> Hi,
>>
>> I think what Edy did here makes sense. We do not need anything fancy
>> for technical documentation and design. This would also be easy to
>> maintain or integrate to the main website (git submodules will help).
>>
>> I have two basic requirements for design space:
>>
>> - commenting so devs can discuss the design
>> - ease of update so we can respond to comments
>>
>> A plain markdown repo would work well for this and both points are
>> possible using github or gerrit workflows.
>>
>> I would actually prefer if we had something that is directly part of
>> the source repositories so we could review code updates and docs
>> updates together. Unfortunately that it is hard to do when we have
>> multiple different components to update. So this proposal is probably
>> the next best thing.
>
>
> I think we need a wiki for this, instead of reinventing one :-)
>
> We have a builtin markdown based wiki in the ovirt site github project.
>
> For discussion, we have the mailing list and other channels like bluejeans
> and irc.
>
> Nir
>
>>
>> --
>> Martin Sivak
>> SLA
>>
>>
>> On Thu, Jun 15, 2017 at 8:11 PM, Edward Haas <ehaas at redhat.com> wrote:
>> > Hi all,
>> >
>> > Came back to this thread due to a need to post some design
>> > documentation.
>> > After fetching the ovirt-site and looking up where to start the
>> > document, I
>> > remembered why I stopped using it.
>> >
>> > After exploring several options, including the GitHub wiki, I think that
>> > for
>> > the development documentation we can just go with the minimum:
>> > Use a repo to just post markdown and image files, letting GitHub
>> > rendering/view of such files to do the job for us.
>> > We can still review the documents and have discussions on the content,
>> > and
>> > provide access to all who wants to use it (to perform the merges).
>> > The fact it uses markdown and images, can allow its content to be
>> > relocated
>> > to any other solutions that will come later on, including adding the
>> > content
>> > back on ovirt-site.
>> >
>> > Here is a simple example:
>> > https://github.com/EdDev/ovirt-devwiki/blob/initial-structure/index.md
>> >
>> > it uses simple markdown md files with relative links to other pages.
>> > Adding
>> > images is also simple.
>> >
>> > What do you think?
>> >
>> > Thanks,
>> > Edy.
>> >
>> >
>> >
>> > On Tue, Feb 7, 2017 at 12:42 PM, Michal Skrivanek
>> > <michal.skrivanek at redhat.com> wrote:
>> >>
>> >>
>> >> On 16 Jan 2017, at 11:13, Roy Golan <rgolan at redhat.com> wrote:
>> >>
>> >>
>> >>
>> >> On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck at redhat.com>
>> >> wrote:
>> >>>
>> >>> Quack,
>> >>>
>> >>> On 01/08/2017 06:39 PM, Barak Korren wrote:
>> >>> > On 8 January 2017 at 10:17, Roy Golan <rgolan at redhat.com> wrote:
>> >>> >> Adding infra which I forgot to add from the beginning
>> >>>
>> >>> Thanks.
>> >>>
>> >>> > I don't think this is an infra issue, more of a community/working
>> >>> > procedures one.
>> >>>
>> >>> I do thin it is. We are involved in the tooling, for their
>> >>> maintenance,
>> >>> for documenting where things are, for suggesting better solutions,
>> >>> ensuring security…
>> >>>
>> >>> > On the one hand, the developers need a place where they create and
>> >>> > discuss design documents and road maps. That please needs to be as
>> >>> > friction-free as possible to allow developers to work on the code
>> >>> > instead of on the documentation tools.
>> >>>
>> >>> As for code, I think there is need for review, even more for design
>> >>> documents, so I don't see why people are bothered by PRs, which is a
>> >>> tool they already know fairly well.
>> >>
>> >>
>> >> because it takes ages to get attention and get it in, even in cases
>> >> when
>> >> the text/update is more of an FYI and doesn’t require feedback.
>> >> That leads to frustration, and that leads to loss of any motivation to
>> >> contribute anything at all.
>> >> You can see people posting on their own platforms, blogs, just to run
>> >> away
>> >> from this one
>> >>
>> >>>
>> >>> For people with few git knowledge, the GitHub web interface allows to
>> >>> edit files.
>> >>>
>> >>> > On the other hand, the user community needs a good, up to date
>> >>> > source
>> >>> > of information about oVirt and how to use it.
>> >>>
>> >>> Yes, this official entry point and it needs to be clean.
>> >>
>> >>
>> >> yep, you’re right about the entry point -like pages
>> >>
>> >>>
>> >>> > Having said the above, I don't think the site project's wiki is the
>> >>> > best place for this. The individual project mirrors on GitHub may be
>> >>> > better for this
>> >>>
>> >>> We could indeed split the technical documentation. If people want to
>> >>> experiment with the GH wiki pages, I won't interfere.
>> >>>
>> >>> I read several people in this thread really miss the old wiki, so I
>> >>> think it is time to remember why we did not stay in paradise. I was
>> >>> not
>> >>> there at the time, but I know the wiki was not well maintained. People
>> >>> are comparing our situation to the MediaWiki site, but the workforce
>> >>> is
>> >>> nowhere to be compared. There is already no community manager, and
>> >>> noone
>> >>> is in charge of any part really, whereas Mediawiki has people in
>> >>> charge
>> >>> of every corner of the wiki. Also they developed tools over years to
>> >>> monitor, correct, revert… and we don't have any of this. So without
>> >>> any
>> >>> process then it was a total mess. More than one year later there was
>> >>> still much cleanup to do, and having contributed to it a little bit, I
>> >>> fear a sentimental rush to go back to a solution that was abandoned.
>> >>
>> >>
>> >> it was also a bit difficult to edit, plus a barrier of ~1 month it took
>> >> to
>> >> get an account
>> >>
>> >>>
>> >>> Having a header telling if this is a draft or published is far from
>> >>> being sufficient. If noone cares you just pile up content that gets
>> >>> obsolete, then useless, then misleading for newcomers. You may prefer
>> >>> review a posteriori, but in this case you need to have the proper tool
>> >>> to be able to search for things to be reviewed, and a in-content
>> >>> pseudo-header is really not an easy way to get a todolist.
>> >>>
>> >>> As for the current builder, it checks every minute for new content to
>> >>> build. The current tool (Middleman) is a bit slow, and the machine is
>> >>> not ultra speedy, but even in the worst case it should not take more
>> >>> than half an hour to see the published result. So I don't know why
>> >>> someone suggested to build "at least once a day". There is also an
>> >>> experimentation to improve this part.
>> >>>
>> >>> So to sum up:
>> >>>   - the most needed thing here is not a tool but people in charge to
>> >>> review the content (additions, cleanup old things, ask devs to update
>> >>> some missing part…), this should also allow for faster publishing
>> >>>   - I'm not against changing tool, just do not forget what you loose
>> >>> in
>> >>> the process, and the migration pain
>> >>>   - I think free editing without workflow in our specific case is not
>> >>> gonna work because we do not have the needed workforce for things to
>> >>> auto-correct
>> >>
>> >>
>> >> I do not think we absolutely have to change a tool, just the process.
>> >> We
>> >> do not need anything fancy, it would be enough to e.g. automatically
>> >> merge
>> >> anything unless -1 from anyone in 48 hours, and maybe add protection
>> >> for few
>> >> intro pages we do not want to let anyone touch
>> >>
>> >>>
>> >>> \_o<
>> >>>
>> >>
>> >> What do you suggest then? how can infra help with this now? fwiw I
>> >> don't
>> >> care only about 'developers', I do want to process to be better.
>> >>
>> >>
>> >> thanks roy for bringing it up
>> >>
>> >> Thanks,
>> >> michal
>> >>
>> >>
>> >> _______________________________________________
>> >> Devel mailing list
>> >> Devel at ovirt.org
>> >> http://lists.ovirt.org/mailman/listinfo/devel
>> >>
>> >>
>> >>
>> >> _______________________________________________
>> >> Users mailing list
>> >> Users at ovirt.org
>> >> http://lists.ovirt.org/mailman/listinfo/users
>> >>
>> >
>> >
>> > _______________________________________________
>> > Users mailing list
>> > Users at ovirt.org
>> > http://lists.ovirt.org/mailman/listinfo/users
>> >
>> _______________________________________________
>> Devel mailing list
>> Devel at ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/devel