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

Tue Jun 20 19:22:02 UTC 2017

בתאריך יום ג׳, 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ovirt.org/pipermail/infra/attachments/20170620/394578ce/attachment.html>