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

Tue Jun 20 20:34:14 UTC 2017

On Tue, Jun 20, 2017 at 10: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.
>

Discussing reviews through emails?? Good luck with that.
What's next? Sending patches through emails?

I want the power of the review (gerrit/github), not a poor alternative.
The only advantage of github over gerrit in this respect is the already
existing rendering
of the md files.

>
>
> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ovirt.org/pipermail/users/attachments/20170620/c5db56de/attachment.html>