10:57 a.m.
I'm getting the feeling I'm not alone in this, authoring and publishing a
wiki page isn't as used to be for long time.
I want to suggest a bit lighter workflow:
1. Everyone can merge their page - (it's a wiki)
Same as with (public and open) code, no one has the motivation to publish
a badly written
wiki page under their name. True, it can have an impact, but not as with
broken code
2. Use Page-Status marker
The author first merges the draft. Its now out there and should be updated
as time goes and its
status is DRAFT. Maintainers will come later and after review would change
the status to
PUBLISH. That could be a header in on the page:
---
page status: DRAFT/PUBLISH
---
Simple I think, and should work.
11 a.m.
On 04/01/17 09:57 +0200, Roy Golan wrote:
I'm getting the feeling I'm not alone in this, authoring and
publishing a
wiki page isn't as used to be for long time.
I want to suggest a bit lighter workflow:
1. Everyone can merge their page - (it's a wiki)
Same as with (public and open) code, no one has the motivation to publish
a badly written
wiki page under their name. True, it can have an impact, but not as with
broken code
2. Use Page-Status marker
The author first merges the draft. Its now out there and should be updated
as time goes and its
status is DRAFT. Maintainers will come later and after review would change
the status to
PUBLISH. That could be a header in on the page:
---
page status: DRAFT/PUBLISH
---
Simple I think, and should work.
+1, github's contribution workflow is terrible and doesn't make any
sense for wiki pages.
_______________________________________________
Devel mailing list
Devel(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
12:17 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
I once tried to edit a broken link in current documentation and lost hope after 10 minutes
of efforts.
Being a sysadmin, I understand the fear of unknown/untrusted people accessing stuff and
performing uncontrolled changes, but generally speaking I believe the majority of this
community is not driven by 10y old cracker attitudes: I trust that the additional value
provided by people will greatly overcome a few typos and errors.
+1
Cheers
AG
-----Original Message-----
From: users-bounces(a)ovirt.org [mailto:users-bounces@ovirt.org] On Behalf Of Martin
Polednik
Sent: Wednesday, January 4, 2017 9:01 AM
To: Roy Golan <rgolan(a)redhat.com>
Cc: users <users(a)ovirt.org>; devel <devel(a)ovirt.org>
Subject: Re: [ovirt-users] Lowering the bar for wiki contribution?
On 04/01/17 09:57 +0200, Roy Golan wrote:
I'm getting the feeling I'm not alone in this, authoring and
publishing
a wiki page isn't as used to be for long time.
I want to suggest a bit lighter workflow:
1. Everyone can merge their page - (it's a wiki)
Same as with (public and open) code, no one has the motivation to
publish a badly written
wiki page under their name. True, it can have an impact, but not as
with broken code
2. Use Page-Status marker
The author first merges the draft. Its now out there and should be
updated as time goes and its status is DRAFT. Maintainers will come
later and after review would change the status to PUBLISH. That could
be a header in on the page:
---
page status: DRAFT/PUBLISH
---
Simple I think, and should work.
+1, github's contribution workflow is terrible and doesn't make any
sense for wiki pages.
_______________________________________________
Devel mailing list
Devel(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________
Users mailing list
Users(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/users
11 a.m.
On Wed, Jan 4, 2017 at 8:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
I'm getting the feeling I'm not alone in this, authoring and
publishing a
wiki page isn't as used to be for long time.
I want to suggest a bit lighter workflow:
1. Everyone can merge their page - (it's a wiki)
Same as with (public and open) code, no one has the motivation to
publish a badly written
wiki page under their name. True, it can have an impact, but not as with
broken code
2. Use Page-Status marker
The author first merges the draft. Its now out there and should be
updated as time goes and its
status is DRAFT. Maintainers will come later and after review would
change the status to
PUBLISH. That could be a header in on the page:
---
page status: DRAFT/PUBLISH
---
Simple I think, and should work.
Sounds very good.
+1
_______________________________________________
Devel mailing list
Devel(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
11:29 a.m.
On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
I'm getting the feeling I'm not alone in this, authoring and
publishing a
wiki page isn't as used to be for long time.
Indeed. Several changes in the process have made it more difficult than it
probably should be.
I want to suggest a bit lighter workflow:
1. Everyone can merge their page - (it's a wiki)
It's not really a wiki. Perhaps parts of the site should be?
Same as with (public and open) code, no one has the motivation to
publish a badly written
wiki page under their name. True, it can have an impact, but not as with
broken code
Does everyone have merge rights in public and open code?
2. Use Page-Status marker
The author first merges the draft. Its now out there and should be
updated as time goes and its
status is DRAFT. Maintainers will come later and after review would
change the status to
PUBLISH. That could be a header in on the page:
---
page status: DRAFT/PUBLISH
---
Interesting idea. How do we ensure we are not left with draft content all
over?
Y.
Simple I think, and should work.
_______________________________________________
Devel mailing list
Devel(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
11:51 a.m.
On 4 January 2017 at 09:57, Roy Golan <rgolan(a)redhat.com> wrote:
I'm getting the feeling I'm not alone in this, authoring and
publishing a
wiki page isn't as used to be for long time.
Maybe we're using the wrong tool for the job?
The site is intentionally not a wiki to allow OSAS some editorial
control over what goes on the public site.
I'm guessing that the scenario you are talking about here is a
developer looking to create a preliminary design document for further
discussion. Maybe we need a different tool and process for that?
--
Barak Korren
bkorren(a)redhat.com
RHCE, RHCi, RHV-DevOps Team
https://ifireball.wordpress.com/
12:06 p.m.
On Wed, Jan 4, 2017 at 10:51 AM, Barak Korren <bkorren(a)redhat.com> wrote:
On 4 January 2017 at 09:57, Roy Golan <rgolan(a)redhat.com>
wrote:
> I'm getting the feeling I'm not alone in this, authoring and publishing a
> wiki page isn't as used to be for long time.
Maybe we're using the wrong tool for the job?
The site is intentionally not a wiki to allow OSAS some editorial
control over what goes on the public site.
I'm guessing that the scenario you are talking about here is a
developer looking to create a preliminary design document for further
discussion. Maybe we need a different tool and process for that?
I agree, we are using the wrong tool for the job of putting initial design
for discussion.
For publishing user documentation the site is ok.
I miss the wiki we had, it was easier to use for development of feature
pages and developer documentation.
Nir
12:16 p.m.
On 4 January 2017 at 11:06, Nir Soffer <nsoffer(a)redhat.com> wrote:
On Wed, Jan 4, 2017 at 10:51 AM, Barak Korren
<bkorren(a)redhat.com> wrote:
> On 4 January 2017 at 09:57, Roy Golan <rgolan(a)redhat.com> wrote:
>> I'm getting the feeling I'm not alone in this, authoring and publishing
a
>> wiki page isn't as used to be for long time.
>
> Maybe we're using the wrong tool for the job?
> The site is intentionally not a wiki to allow OSAS some editorial
> control over what goes on the public site.
>
> I'm guessing that the scenario you are talking about here is a
> developer looking to create a preliminary design document for further
> discussion. Maybe we need a different tool and process for that?
I agree, we are using the wrong tool for the job of putting initial design
for discussion.
For publishing user documentation the site is ok.
I miss the wiki we had, it was easier to use for development of feature
pages and developer documentation.
Who is our OSAS contact these days?
Nir
12:38 p.m.
On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
I'm getting the feeling I'm not alone in this, authoring and
publishing a
wiki page isn't as used to be for long time.
I want to suggest a bit lighter workflow:
1. Everyone can merge their page - (it's a wiki)
Same as with (public and open) code, no one has the motivation to
publish a badly written
wiki page under their name. True, it can have an impact, but not as with
broken code
+1.
Moreover, I think we shouldn't block any merging. Instead, wiki
maintainers
could act afterwards and revert when needed (Wikipedia style). Another
issue is that (sadly) unlike mediawiki, we need to wait for wiki publish
after a change. So I'd suggest to build and publish the wiki at least once
a day. Any way, I think we should make the workflow much more intuitive and
pleasant like the previous wiki - i.e. much less restrictive than
manipulating a code base.
2. Use Page-Status marker
The author first merges the draft. Its now out there and should be
updated as time goes and its
status is DRAFT. Maintainers will come later and after review would
change the status to
PUBLISH. That could be a header in on the page:
---
page status: DRAFT/PUBLISH
---
Simple I think, and should work.
_______________________________________________
Devel mailing list
Devel(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
1:17 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
On Wed, Jan 4, 2017 at 11:38 AM, Daniel Erez <derez(a)redhat.com> wrote:
On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
> I'm getting the feeling I'm not alone in this, authoring and publishing a
> wiki page isn't as used to be for long time.
>
> I want to suggest a bit lighter workflow:
>
> 1. Everyone can merge their page - (it's a wiki)
> Same as with (public and open) code, no one has the motivation to
> publish a badly written
> wiki page under their name. True, it can have an impact, but not as
> with broken code
>
>
+1.
Moreover, I think we shouldn't block any merging. Instead, wiki
maintainers could act afterwards and revert when needed (Wikipedia style).
Another issue is that (sadly) unlike mediawiki, we need to wait for wiki
publish after a change. So I'd suggest to build and publish the wiki at
least once a day. Any way, I think we should make the workflow much more
intuitive and pleasant like the previous wiki - i.e. much less restrictive
than manipulating a code base.
> 2. Use Page-Status marker
> The author first merges the draft. Its now out there and should be
> updated as time goes and its
> status is DRAFT. Maintainers will come later and after review would
> change the status to
> PUBLISH. That could be a header in on the page:
> ---
> page status: DRAFT/PUBLISH
> ---
>
> Simple I think, and should work.
>
>
+1
The effort of maintaining the wiki today compare to how it used to be
before is much more cumbersome and problematic.
I think we can learn a lot from wikipedia workflow,
It is a much more inviting process where anyone can change the content
easily.
I'm not saying we should let any anonymous user change the wiki but even if
we make it easier in house we can achieve much more informative reliable
and updated wiki.
>
>
> _______________________________________________
> Devel mailing list
> Devel(a)ovirt.org
> http://lists.ovirt.org/mailman/listinfo/devel
>
_______________________________________________
Users mailing list
Users(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/users
1:41 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
On 4 January 2017 at 12:17, Maor Lipchuk <mlipchuk(a)redhat.com> wrote:
On Wed, Jan 4, 2017 at 11:38 AM, Daniel Erez <derez(a)redhat.com> wrote:
>
>
> On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
>
>> I'm getting the feeling I'm not alone in this, authoring and publishing
>> a wiki page isn't as used to be for long time.
>>
>> I want to suggest a bit lighter workflow:
>>
>> 1. Everyone can merge their page - (it's a wiki)
>> Same as with (public and open) code, no one has the motivation to
>> publish a badly written
>> wiki page under their name. True, it can have an impact, but not as
>> with broken code
>>
>>
> +1.
> Moreover, I think we shouldn't block any merging. Instead, wiki
> maintainers could act afterwards and revert when needed (Wikipedia style).
> Another issue is that (sadly) unlike mediawiki, we need to wait for wiki
> publish after a change. So I'd suggest to build and publish the wiki at
> least once a day. Any way, I think we should make the workflow much more
> intuitive and pleasant like the previous wiki - i.e. much less restrictive
> than manipulating a code base.
>
>
>> 2. Use Page-Status marker
>> The author first merges the draft. Its now out there and should be
>> updated as time goes and its
>> status is DRAFT. Maintainers will come later and after review would
>> change the status to
>> PUBLISH. That could be a header in on the page:
>> ---
>> page status: DRAFT/PUBLISH
>> ---
>>
>> Simple I think, and should work.
>>
>>
+1
The effort of maintaining the wiki today compare to how it used to be
before is much more cumbersome and problematic.
I think we can learn a lot from wikipedia workflow,
It is a much more inviting process where anyone can change the content
easily.
I'm not saying we should let any anonymous user change the wiki but even
if we make it easier in house we can achieve much more informative reliable
and updated wiki.
I really think Github Pages is a perfect fit and an alternative to my first
suggestion. see
https://github.com/oVirt/ovirt-site/wiki/Why-aren't-we-using-this%3F
>>
>>
>> _______________________________________________
>> Devel mailing list
>> Devel(a)ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/devel
>>
>
>
> _______________________________________________
> Users mailing list
> Users(a)ovirt.org
> http://lists.ovirt.org/mailman/listinfo/users
>
>
1:49 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
On Wed, Jan 4, 2017 at 12:41 PM, Roy Golan <rgolan(a)redhat.com> wrote:
On 4 January 2017 at 12:17, Maor Lipchuk <mlipchuk(a)redhat.com> wrote:
>
>
>
> On Wed, Jan 4, 2017 at 11:38 AM, Daniel Erez <derez(a)redhat.com> wrote:
>>
>>
>>
>> On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
>>>
>>> I'm getting the feeling I'm not alone in this, authoring and
publishing
>>> a wiki page isn't as used to be for long time.
>>>
>>> I want to suggest a bit lighter workflow:
>>>
>>> 1. Everyone can merge their page - (it's a wiki)
>>> Same as with (public and open) code, no one has the motivation to
>>> publish a badly written
>>> wiki page under their name. True, it can have an impact, but not as
>>> with broken code
>>>
>>
>> +1.
>> Moreover, I think we shouldn't block any merging. Instead, wiki
>> maintainers could act afterwards and revert when needed (Wikipedia style).
>> Another issue is that (sadly) unlike mediawiki, we need to wait for wiki
>> publish after a change. So I'd suggest to build and publish the wiki at
>> least once a day. Any way, I think we should make the workflow much more
>> intuitive and pleasant like the previous wiki - i.e. much less restrictive
>> than manipulating a code base.
>>
>>
>>>
>>> 2. Use Page-Status marker
>>> The author first merges the draft. Its now out there and should be
>>> updated as time goes and its
>>> status is DRAFT. Maintainers will come later and after review would
>>> change the status to
>>> PUBLISH. That could be a header in on the page:
>>> ---
>>> page status: DRAFT/PUBLISH
>>> ---
>>>
>>> Simple I think, and should work.
>>>
>
> +1
> The effort of maintaining the wiki today compare to how it used to be
> before is much more cumbersome and problematic.
> I think we can learn a lot from wikipedia workflow,
> It is a much more inviting process where anyone can change the content
> easily.
> I'm not saying we should let any anonymous user change the wiki but even
> if we make it easier in house we can achieve much more informative reliable
> and updated wiki.
>
I really think Github Pages is a perfect fit and an alternative to my first
suggestion. see
https://github.com/oVirt/ovirt-site/wiki/Why-aren't-we-using-this%3F
This is not github pages, this is the builtin wiki, but we can use this for
developing content.
>>>
>>>
>>>
>>>
>>> _______________________________________________
>>> Devel mailing list
>>> Devel(a)ovirt.org
>>> http://lists.ovirt.org/mailman/listinfo/devel
>>
>>
>>
>> _______________________________________________
>> Users mailing list
>> Users(a)ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/users
>>
>
_______________________________________________
Users mailing list
Users(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/users
3:44 a.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
On Wed, Jan 4, 2017 at 11:41 AM, Roy Golan <rgolan(a)redhat.com> wrote:
On 4 January 2017 at 12:17, Maor Lipchuk <mlipchuk(a)redhat.com> wrote:
>
>
>
> On Wed, Jan 4, 2017 at 11:38 AM, Daniel Erez <derez(a)redhat.com> wrote:
>>
>>
>>
>> On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
>>>
>>> I'm getting the feeling I'm not alone in this, authoring and
publishing
>>> a wiki page isn't as used to be for long time.
>>>
>>> I want to suggest a bit lighter workflow:
>>>
>>> 1. Everyone can merge their page - (it's a wiki)
>>> Same as with (public and open) code, no one has the motivation to
>>> publish a badly written
>>> wiki page under their name. True, it can have an impact, but not as
>>> with broken code
>>>
>>
>> +1.
>> Moreover, I think we shouldn't block any merging. Instead, wiki
>> maintainers could act afterwards and revert when needed (Wikipedia style).
>> Another issue is that (sadly) unlike mediawiki, we need to wait for wiki
>> publish after a change. So I'd suggest to build and publish the wiki at
>> least once a day. Any way, I think we should make the workflow much more
>> intuitive and pleasant like the previous wiki - i.e. much less restrictive
>> than manipulating a code base.
>>
>>
>>>
>>> 2. Use Page-Status marker
>>> The author first merges the draft. Its now out there and should be
>>> updated as time goes and its
>>> status is DRAFT. Maintainers will come later and after review would
>>> change the status to
>>> PUBLISH. That could be a header in on the page:
>>> ---
>>> page status: DRAFT/PUBLISH
>>> ---
>>>
>>> Simple I think, and should work.
>>>
>
> +1
> The effort of maintaining the wiki today compare to how it used to be
> before is much more cumbersome and problematic.
> I think we can learn a lot from wikipedia workflow,
> It is a much more inviting process where anyone can change the content
> easily.
> I'm not saying we should let any anonymous user change the wiki but even
> if we make it easier in house we can achieve much more informative reliable
> and updated wiki.
>
I really think Github Pages is a perfect fit and an alternative to my first
suggestion. see
https://github.com/oVirt/ovirt-site/wiki/Why-aren't-we-using-this%3F
+1
Github wiki would allow us instant publishing, review after after
publishing, it works purely in browser (no need for running local ruby
server) and it's a service that doesn't require any maintenance form
our side.
>>>
>>>
>>>
>>>
>>> _______________________________________________
>>> Devel mailing list
>>> Devel(a)ovirt.org
>>> http://lists.ovirt.org/mailman/listinfo/devel
>>
>>
>>
>> _______________________________________________
>> Users mailing list
>> Users(a)ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/users
>>
>
_______________________________________________
Users mailing list
Users(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/users
11:17 a.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
Adding infra which I forgot to add from the beginning
On 7 January 2017 at 02:44, Jakub Niedermertl <jniederm(a)redhat.com> wrote:
On Wed, Jan 4, 2017 at 11:41 AM, Roy Golan <rgolan(a)redhat.com>
wrote:
>
>
> On 4 January 2017 at 12:17, Maor Lipchuk <mlipchuk(a)redhat.com> wrote:
>>
>>
>>
>> On Wed, Jan 4, 2017 at 11:38 AM, Daniel Erez <derez(a)redhat.com> wrote:
>>>
>>>
>>>
>>> On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan(a)redhat.com> wrote:
>>>>
>>>> I'm getting the feeling I'm not alone in this, authoring and
publishing
>>>> a wiki page isn't as used to be for long time.
>>>>
>>>> I want to suggest a bit lighter workflow:
>>>>
>>>> 1. Everyone can merge their page - (it's a wiki)
>>>> Same as with (public and open) code, no one has the motivation to
>>>> publish a badly written
>>>> wiki page under their name. True, it can have an impact, but not as
>>>> with broken code
>>>>
>>>
>>> +1.
>>> Moreover, I think we shouldn't block any merging. Instead, wiki
>>> maintainers could act afterwards and revert when needed (Wikipedia
style).
>>> Another issue is that (sadly) unlike mediawiki, we need to wait for
wiki
>>> publish after a change. So I'd suggest to build and publish the wiki at
>>> least once a day. Any way, I think we should make the workflow much
more
>>> intuitive and pleasant like the previous wiki - i.e. much less
restrictive
>>> than manipulating a code base.
>>>
>>>
>>>>
>>>> 2. Use Page-Status marker
>>>> The author first merges the draft. Its now out there and should be
>>>> updated as time goes and its
>>>> status is DRAFT. Maintainers will come later and after review would
>>>> change the status to
>>>> PUBLISH. That could be a header in on the page:
>>>> ---
>>>> page status: DRAFT/PUBLISH
>>>> ---
>>>>
>>>> Simple I think, and should work.
>>>>
>>
>> +1
>> The effort of maintaining the wiki today compare to how it used to be
>> before is much more cumbersome and problematic.
>> I think we can learn a lot from wikipedia workflow,
>> It is a much more inviting process where anyone can change the content
>> easily.
>> I'm not saying we should let any anonymous user change the wiki but even
>> if we make it easier in house we can achieve much more informative
reliable
>> and updated wiki.
>>
>
>
>
> I really think Github Pages is a perfect fit and an alternative to my
first
> suggestion. see
> https://github.com/oVirt/ovirt-site/wiki/Why-aren't-we-using-this%3F
+1
Github wiki would allow us instant publishing, review after after
publishing, it works purely in browser (no need for running local ruby
server) and it's a service that doesn't require any maintenance form
our side.
>>>>
>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> Devel mailing list
>>>> Devel(a)ovirt.org
>>>> http://lists.ovirt.org/mailman/listinfo/devel
>>>
>>>
>>>
>>> _______________________________________________
>>> Users mailing list
>>> Users(a)ovirt.org
>>> http://lists.ovirt.org/mailman/listinfo/users
>>>
>>
>
>
> _______________________________________________
> Users mailing list
> Users(a)ovirt.org
> http://lists.ovirt.org/mailman/listinfo/users
>
12:39 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
On 8 January 2017 at 10:17, Roy Golan <rgolan(a)redhat.com> wrote:
Adding infra which I forgot to add from the beginning
I don't think this is an infra issue, more of a community/working
procedures one.
I'm going to state my view on this, the same one I've stated before,
with hopes of reaching a conclusion that will be beneficial to
everyone.
The core of the issue here is that we have two conflicting needs.
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.
On the other hand, the user community needs a good, up to date source
of information about oVirt and how to use it. To keep the information
quality high, there is a need for some editorial process. The OSAS
team stepped in to offer editorial services and is doing tremendous
work behind the scenes. This creates the desire to use the same tools
and flows that OSAS is using for other projects.
One thing that I don't thing is a hard requirement, is to have the
design documents on the main oVirt website. In fact, I think that the
(Typically outdated) design documents being stored on the main site,
and linked to as "features" had been a major source of confusion for
users.
This all leads me to the conclusion that the currently offered
solution, of using the GitHub project wiki feature may indeed be the
appropriate solution for this (Even though I personally resent the
growing dependency of open source projects on proprietary
closed-source online platforms).
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 (I've enabled the wiki for engine [1] and vdsm [2] for
example). For system-wide features, I suppose OST [2] will be
appropriate, with hopes that this will provide some incentive to write
tests for those features.
[1]: https://github.com/oVirt/ovirt-engine/wiki
[2]: https://github.com/oVirt/vdsm/wiki
[3]: https://github.com/oVirt/ovirt-system-tests/wiki
--
Barak Korren
bkorren(a)redhat.com
RHCE, RHCi, RHV-DevOps Team
https://ifireball.wordpress.com/
6:06 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--iANP26gIIpJf21NXLwmkR189pjBFPVhEh
Content-Type: multipart/mixed; boundary="usQaNKwP9cithUMUDf3HTdxAGAIlqORMv";
protected-headers="v1"
From: =?UTF-8?B?TWFyYyBEZXF1w6huZXMgKER1Y2sp?= <duck(a)redhat.com>
To: Barak Korren <bkorren(a)redhat.com>, Roy Golan <rgolan(a)redhat.com>
Cc: devel <devel(a)ovirt.org>, users <users(a)ovirt.org>, infra
<infra(a)ovirt.org>
Message-ID: <6e6f7b97-9d8d-1759-5dab-c64bba86de35(a)redhat.com>
Subject: Re: [ovirt-devel] [ovirt-users] Lowering the bar for wiki
contribution?
References: <CAC_JqcnVfGeFm+xQmZU-QEbp57efphO3jhPw5rDqux7d0DCu9A(a)mail.gmail.com>
<CAP84NrtLshq30DJPmJ6==p2DThWokKqBetKpmhKFp+r-E2CVpw(a)mail.gmail.com>
<CAJ1JNOcxk-=Aodrc0gM7hdJi-N0nyn+vwTkbjyTEKMZNGZXZ3A(a)mail.gmail.com>
<CAC_Jqcnkqo3sGyBqc61zo7qN61ua0ZM1f1oTPkXHcH=L2_-HQg(a)mail.gmail.com>
<CAJVw3Ezs9bSn=OLyLRfkz=twJNn1LuzdAjbV0qTyvAcVS+KF2w(a)mail.gmail.com>
<CAC_Jqcku_hmpF25n4Ekrdsq4SzXRWsc0jGxbSeOyao3Snie4WQ(a)mail.gmail.com>
<CAGJrMmqKJAycawV91RDxGF5ERB3snt6s9PNtfjCPmsRO4619qA(a)mail.gmail.com>
In-Reply-To: <CAGJrMmqKJAycawV91RDxGF5ERB3snt6s9PNtfjCPmsRO4619qA(a)mail.gmail.com>
--usQaNKwP9cithUMUDf3HTdxAGAIlqORMv
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
On 8 January 2017 at 10:17, Roy Golan <rgolan(a)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=85
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.
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.=20
Yes, this official entry point and it needs to be clean.
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=85 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.
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=85), 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
\_o<
--usQaNKwP9cithUMUDf3HTdxAGAIlqORMv--
--iANP26gIIpJf21NXLwmkR189pjBFPVhEh
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCgAdFiEEcpcqg+UmRT3yiF+BVen596wcRD8FAlh2SdoACgkQVen596wc
RD/UDQ/6AsWCHvORKuOJycfXpyM+P6H4dB0nwjMTh2RPFHu/1ErPgUtYBogjUFro
+ds7fbagUcbE4q1Rq2KY8CmoRBGfEZ8zz148fE8Q51O4QREl+0TskR6zRbczQD4U
osLH7ekDc53FgA+3GySDySeSMBEW797eZzTWjayjDXFoQSIF+8p8RNs+ZUD5Ix1G
jZccnQLX22mBHPwkPBf+E1mq3EmHSSTb9kvKrSjs4JdwthxBRlzrqM3HWaSWDnqv
IbyzoOPbRvp8ixru6kIfiwKtt5C9BZgMCeFKfBQzn21FUxu+Z9H+psz7a8PGhHkV
ckZ/6tAkYCZmTRjn4WRRDhUTdshhHK1p79mEMFNo0CR6e8H3PRvEsVtqDSJZCTGC
wlUleWt8RWC0IkvC4dFpF3IgovDl8kMA6fM/+s12tnJzYWAE0QVvNVJguNolDEOq
haQZ6Fm0PA+i8MtvAQBP+bYNQNA1Pw5bq/wIDQL+oyOCTAaa30gLJqqbn2bCUg6Z
pMo8sOsgl+tDniZ6kw9LiMpjDcajV8g3iRfGnez4KsoOVcy6SY0gfzbRI4UGT8HX
hgWp58hhlBGLoiP6cvnJYECSdE74m89Y4E3JPy8cIJRk/8Y99JHiXgOaSHEjHLeW
sphoCLUm8PfllqmbH3QN5vjiqitfTDDUmo6FpQB6n2CwbBPOFAQ=
=DknS
-----END PGP SIGNATURE-----
--iANP26gIIpJf21NXLwmkR189pjBFPVhEh--
1:13 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck(a)redhat.com> wrote:
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
> On 8 January 2017 at 10:17, Roy Golan <rgolan(a)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.
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.
> 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.
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
\_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.
1:42 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
--Apple-Mail=_9F416020-C8F4-48D9-A648-B6277A20911E
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
charset=utf-8
On 16 Jan 2017, at 11:13, Roy Golan <rgolan(a)redhat.com> wrote:
=20
=20
=20
On 11 January 2017 at 17:06, Marc Dequ=C3=A8nes (Duck) =
<duck(a)redhat.com
<mailto:duck@redhat.com>> wrote:
Quack,
=20
On 01/08/2017 06:39 PM, Barak Korren wrote:
> On 8 January 2017 at 10:17, Roy Golan <rgolan(a)redhat.com =
<mailto:rgolan@redhat.com>> wrote:
>> Adding infra which I forgot to add from the beginning
=20
Thanks.
=20
> I don't think this is an infra issue, more of a community/working
> procedures one.
=20
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=E2=80=A6
=20
> 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.
=20
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=E2=80=99t require feedback.=20=
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
=20
For people with few git knowledge, the GitHub web interface allows to
edit files.
=20
> On the other hand, the user community needs a good, up to date =
source
> of information about oVirt and how to use it.
=20
Yes, this official entry point and it needs to be clean.
yep, you=E2=80=99re right about the entry point -like pages
=20
> 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
=20
We could indeed split the technical documentation. If people want to
experiment with the GH wiki pages, I won't interfere.
=20
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=E2=80=A6 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
=20
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.
=20
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.
=20
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=E2=80=A6), 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
=20
\_o<
=20
=20
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. =20
thanks roy for bringing it up
Thanks,
michal
=20
_______________________________________________
Devel mailing list
Devel(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
--Apple-Mail=_9F416020-C8F4-48D9-A648-B6277A20911E
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
charset=utf-8
<html><head><meta http-equiv=3D"Content-Type"
content=3D"text/html =
charset=3Dutf-8"></head><body style=3D"word-wrap: break-word; =
-webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" =
class=3D""><br class=3D""><div><blockquote
type=3D"cite" class=3D""><div =
class=3D"">On 16 Jan 2017, at 11:13, Roy Golan <<a =
href=3D"mailto:rgolan@redhat.com"
class=3D"">rgolan(a)redhat.com</a>&gt; =
wrote:</div><br class=3D"Apple-interchange-newline"><div
class=3D""><div =
dir=3D"ltr" class=3D""><br class=3D""><div
class=3D"gmail_extra"><br =
class=3D""><div class=3D"gmail_quote">On 11 January 2017 at
17:06, Marc =
Dequ=C3=A8nes (Duck) <span dir=3D"ltr" class=3D""><<a
=
href=3D"mailto:duck@redhat.com" target=3D"_blank" =
class=3D"">duck(a)redhat.com</a>&gt;</span> wrote:<br
class=3D""><blockquote=
class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc =
solid;padding-left:1ex">Quack,<br class=3D"">
<span class=3D""><br class=3D"">
On 01/08/2017 06:39 PM, Barak Korren wrote:<br class=3D"">
> On 8 January 2017 at 10:17, Roy Golan <<a =
href=3D"mailto:rgolan@redhat.com"
class=3D"">rgolan(a)redhat.com</a>&gt; =
wrote:<br class=3D"">
>> Adding infra which I forgot to add from the beginning<br =
class=3D"">
<br class=3D"">
</span>Thanks.<br class=3D"">
<span class=3D""><br class=3D"">
> I don't think this is an infra issue, more of a =
community/working<br class=3D"">
> procedures one.<br class=3D"">
<br class=3D"">
</span>I do thin it is. We are involved in the tooling, for their =
maintenance,<br class=3D"">
for documenting where things are, for suggesting better solutions,<br =
class=3D"">
ensuring security=E2=80=A6<br class=3D"">
<span class=3D""><br class=3D"">
> On the one hand, the developers need a place where they create =
and<br class=3D"">
> discuss design documents and road maps. That please needs to be =
as<br class=3D"">
> friction-free as possible to allow developers to work on the =
code<br class=3D"">
> instead of on the documentation tools.<br class=3D"">
<br class=3D"">
</span>As for code, I think there is need for review, even more for =
design<br class=3D"">
documents, so I don't see why people are bothered by PRs, which is a<br =
class=3D"">
tool they already know fairly well.<br =
class=3D""></blockquote></div></div></div></div></blockquote><div><br
=
class=3D""></div>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=E2=80=99t =
require feedback. </div><div>That leads to frustration, and that =
leads to loss of any motivation to contribute anything at =
all.</div><div>You can see people posting on their own platforms, blogs, =
just to run away from this one</div><div><br
class=3D""><blockquote =
type=3D"cite" class=3D""><div class=3D""><div
dir=3D"ltr" class=3D""><div =
class=3D"gmail_extra"><div
class=3D"gmail_quote"><blockquote =
class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc =
solid;padding-left:1ex">
<br class=3D"">
For people with few git knowledge, the GitHub web interface allows to<br =
class=3D"">
edit files.<br class=3D"">
<span class=3D""><br class=3D"">
> On the other hand, the user community needs a good, up to date =
source<br class=3D"">
> of information about oVirt and how to use it.<br class=3D"">
<br class=3D"">
</span>Yes, this official entry point and it needs to be clean.<br =
class=3D""></blockquote></div></div></div></div></blockquote><div><br
=
class=3D""></div>yep, you=E2=80=99re right about the entry point -like
=
pages</div><div><br class=3D""><blockquote
type=3D"cite" class=3D""><div =
class=3D""><div dir=3D"ltr" class=3D""><div
class=3D"gmail_extra"><div =
class=3D"gmail_quote"><blockquote class=3D"gmail_quote"
style=3D"margin:0 =
0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=3D""><br class=3D"">
> Having said the above, I don't think the site project's wiki is =
the<br class=3D"">
> best place for this. The individual project mirrors on GitHub may =
be<br class=3D"">
> better for this<br class=3D"">
<br class=3D"">
</span>We could indeed split the technical documentation. If people want =
to<br class=3D"">
experiment with the GH wiki pages, I won't interfere.<br class=3D"">
<br class=3D"">
I read several people in this thread really miss the old wiki, so I<br =
class=3D"">
think it is time to remember why we did not stay in paradise. I was =
not<br class=3D"">
there at the time, but I know the wiki was not well maintained. =
People<br class=3D"">
are comparing our situation to the MediaWiki site, but the workforce =
is<br class=3D"">
nowhere to be compared. There is already no community manager, and =
noone<br class=3D"">
is in charge of any part really, whereas Mediawiki has people in =
charge<br class=3D"">
of every corner of the wiki. Also they developed tools over years to<br =
class=3D"">
monitor, correct, revert=E2=80=A6 and we don't have any of this. So =
without any<br class=3D"">
process then it was a total mess. More than one year later there was<br =
class=3D"">
still much cleanup to do, and having contributed to it a little bit, =
I<br class=3D"">
fear a sentimental rush to go back to a solution that was abandoned.<br =
class=3D""></blockquote></div></div></div></div></blockquote><div><br
=
class=3D""></div>it was also a bit difficult to edit, plus a barrier of
=
~1 month it took to get an account</div><div><br
class=3D""><blockquote =
type=3D"cite" class=3D""><div class=3D""><div
dir=3D"ltr" class=3D""><div =
class=3D"gmail_extra"><div
class=3D"gmail_quote"><blockquote =
class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc =
solid;padding-left:1ex">
<br class=3D"">
Having a header telling if this is a draft or published is far from<br =
class=3D"">
being sufficient. If noone cares you just pile up content that gets<br =
class=3D"">
obsolete, then useless, then misleading for newcomers. You may prefer<br =
class=3D"">
review a posteriori, but in this case you need to have the proper =
tool<br class=3D"">
to be able to search for things to be reviewed, and a in-content<br =
class=3D"">
pseudo-header is really not an easy way to get a todolist.<br class=3D"">
<br class=3D"">
As for the current builder, it checks every minute for new content to<br =
class=3D"">
build. The current tool (Middleman) is a bit slow, and the machine is<br =
class=3D"">
not ultra speedy, but even in the worst case it should not take more<br =
class=3D"">
than half an hour to see the published result. So I don't know why<br =
class=3D"">
someone suggested to build "at least once a day". There is also an<br =
class=3D"">
experimentation to improve this part.<br class=3D"">
<br class=3D"">
So to sum up:<br class=3D"">
- the most needed thing here is not a tool but people in charge =
to<br class=3D"">
review the content (additions, cleanup old things, ask devs to update<br =
class=3D"">
some missing part=E2=80=A6), this should also allow for faster =
publishing<br class=3D"">
- I'm not against changing tool, just do not forget what you =
loose in<br class=3D"">
the process, and the migration pain<br class=3D"">
- I think free editing without workflow in our specific case is =
not<br class=3D"">
gonna work because we do not have the needed workforce for things to<br =
class=3D"">
auto-correct<br =
class=3D""></blockquote></div></div></div></div></blockquote><div><br
=
class=3D""></div>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</div><div><br class=3D""><blockquote
type=3D"cite" class=3D""><div =
class=3D""><div dir=3D"ltr" class=3D""><div
class=3D"gmail_extra"><div =
class=3D"gmail_quote"><blockquote class=3D"gmail_quote"
style=3D"margin:0 =
0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br class=3D"">
\_o<<br class=3D"">
<br class=3D""></blockquote><div class=3D""><br
class=3D""></div><div =
class=3D"">What do you suggest then? how can infra help with this now? =
fwiw I don't<br class=3D""></div><div
class=3D"">care only about =
'developers', I do want to process to be better. <br =
class=3D""></div></div></div></div></div></blockquote><div><br
=
class=3D""></div>thanks roy for bringing it
up</div><div><br =
class=3D""></div><div>Thanks,</div><div>michal</div><div><br
=
class=3D""><blockquote type=3D"cite"
class=3D""><div class=3D""><div =
dir=3D"ltr" class=3D""><div
class=3D"gmail_extra"><br =
class=3D""></div></div>
_______________________________________________<br class=3D"">Devel =
mailing list<br class=3D""><a href=3D"mailto:Devel@ovirt.org"
=
class=3D"">Devel(a)ovirt.org</a><br =
class=3D"">http://lists.ovirt.org/mailman/listinfo/devel<...
</div><br class=3D""></body></html>=
--Apple-Mail=_9F416020-C8F4-48D9-A648-B6277A20911E--
9:11 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
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(a)redhat.com> wrote:
On 16 Jan 2017, at 11:13, Roy Golan <rgolan(a)redhat.com> wrote:
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck(a)redhat.com> wrote:
> Quack,
>
> On 01/08/2017 06:39 PM, Barak Korren wrote:
> > On 8 January 2017 at 10:17, Roy Golan <rgolan(a)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(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________
Users mailing list
Users(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/users
1:09 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
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.
--
Martin Sivak
SLA
On Thu, Jun 15, 2017 at 8:11 PM, Edward Haas <ehaas(a)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(a)redhat.com> wrote:
>
>
> On 16 Jan 2017, at 11:13, Roy Golan <rgolan(a)redhat.com> wrote:
>
>
>
> On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck(a)redhat.com> wrote:
>>
>> Quack,
>>
>> On 01/08/2017 06:39 PM, Barak Korren wrote:
>> > On 8 January 2017 at 10:17, Roy Golan <rgolan(a)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(a)ovirt.org
> http://lists.ovirt.org/mailman/listinfo/devel
>
>
>
> _______________________________________________
> Users mailing list
> Users(a)ovirt.org
> http://lists.ovirt.org/mailman/listinfo/users
>
_______________________________________________
Users mailing list
Users(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/users
10:22 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak <msivak(a)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(a)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(a)redhat.com> wrote:
>>
>>
>> On 16 Jan 2017, at 11:13, Roy Golan <rgolan(a)redhat.com> wrote:
>>
>>
>>
>> On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck(a)redhat.com>
wrote:
>>>
>>> Quack,
>>>
>>> On 01/08/2017 06:39 PM, Barak Korren wrote:
>>> > On 8 January 2017 at 10:17, Roy Golan <rgolan(a)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(a)ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/devel
>>
>>
>>
>> _______________________________________________
>> Users mailing list
>> Users(a)ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/users
>>
>
>
> _______________________________________________
> Users mailing list
> Users(a)ovirt.org
> http://lists.ovirt.org/mailman/listinfo/users
>
_______________________________________________
Devel mailing list
Devel(a)ovirt.org
http://lists.ovirt.org/mailman/listinfo/devel
11:34 p.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
On Tue, Jun 20, 2017 at 10:22 PM, Nir Soffer <nsoffer(a)redhat.com> wrote:
בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak <msivak(a)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(a)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(a)redhat.com> wrote:
> >>
> >>
> >> On 16 Jan 2017, at 11:13, Roy Golan <rgolan(a)redhat.com> wrote:
> >>
> >>
> >>
> >> On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck(a)redhat.com>
> wrote:
> >>>
> >>> Quack,
> >>>
> >>> On 01/08/2017 06:39 PM, Barak Korren wrote:
> >>> > On 8 January 2017 at 10:17, Roy Golan <rgolan(a)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(a)ovirt.org
> >> http://lists.ovirt.org/mailman/listinfo/devel
> >>
> >>
> >>
> >> _______________________________________________
> >> Users mailing list
> >> Users(a)ovirt.org
> >> http://lists.ovirt.org/mailman/listinfo/users
> >>
> >
> >
> > _______________________________________________
> > Users mailing list
> > Users(a)ovirt.org
> > http://lists.ovirt.org/mailman/listinfo/users
> >
> _______________________________________________
> Devel mailing list
> Devel(a)ovirt.org
> http://lists.ovirt.org/mailman/listinfo/devel
11:29 a.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
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(a)redhat.com> wrote:
>
> בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak <msivak(a)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(a)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(a)redhat.com> wrote:
>> >>
>> >>
>> >> On 16 Jan 2017, at 11:13, Roy Golan <rgolan(a)redhat.com> wrote:
>> >>
>> >>
>> >>
>> >> On 11 January 2017 at 17:06, Marc Dequènes (Duck)
<duck(a)redhat.com>
>> >> wrote:
>> >>>
>> >>> Quack,
>> >>>
>> >>> On 01/08/2017 06:39 PM, Barak Korren wrote:
>> >>> > On 8 January 2017 at 10:17, Roy Golan <rgolan(a)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(a)ovirt.org
>> >> http://lists.ovirt.org/mailman/listinfo/devel
>> >>
>> >>
>> >>
>> >> _______________________________________________
>> >> Users mailing list
>> >> Users(a)ovirt.org
>> >> http://lists.ovirt.org/mailman/listinfo/users
>> >>
>> >
>> >
>> > _______________________________________________
>> > Users mailing list
>> > Users(a)ovirt.org
>> > http://lists.ovirt.org/mailman/listinfo/users
>> >
>> _______________________________________________
>> Devel mailing list
>> Devel(a)ovirt.org
>> http://lists.ovirt.org/mailman/listinfo/devel
7:34 a.m.
New subject: [ovirt-users] Lowering the bar for wiki contribution?
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(a)redhat.com>
To: Martin Sivak <msivak(a)redhat.com>, Nir Soffer <nsoffer(a)redhat.com>
Cc: Edward Haas <edwardh(a)redhat.com>, devel <devel(a)ovirt.org>,
infra <infra(a)ovirt.org>, users <users(a)ovirt.org>
Message-ID: <24cf31c6-0b1e-cf4c-6843-d44f63b5d4e4(a)redhat.com>
Subject: Re: [ovirt-devel] [ovirt-users] Lowering the bar for wiki
contribution?
References: <CAC_JqcnVfGeFm+xQmZU-QEbp57efphO3jhPw5rDqux7d0DCu9A(a)mail.gmail.com>
<CAP84NrtLshq30DJPmJ6==p2DThWokKqBetKpmhKFp+r-E2CVpw(a)mail.gmail.com>
<CAJ1JNOcxk-=Aodrc0gM7hdJi-N0nyn+vwTkbjyTEKMZNGZXZ3A(a)mail.gmail.com>
<CAC_Jqcnkqo3sGyBqc61zo7qN61ua0ZM1f1oTPkXHcH=L2_-HQg(a)mail.gmail.com>
<CAJVw3Ezs9bSn=OLyLRfkz=twJNn1LuzdAjbV0qTyvAcVS+KF2w(a)mail.gmail.com>
<CAC_Jqcku_hmpF25n4Ekrdsq4SzXRWsc0jGxbSeOyao3Snie4WQ(a)mail.gmail.com>
<CAGJrMmqKJAycawV91RDxGF5ERB3snt6s9PNtfjCPmsRO4619qA(a)mail.gmail.com>
<6e6f7b97-9d8d-1759-5dab-c64bba86de35(a)redhat.com>
<CAC_Jqcn6-OUKKDz2B=SF_aqwys9qrSQ+Zdhi5H8=8F_4De5Egg(a)mail.gmail.com>
<F6E943F2-E8A2-43A1-8EF0-F08EEC60A2D5(a)redhat.com>
<CALmkdFQM4XgtQ+opmBD9WiRQhv1puoOEj_Vn9dfS9OeSqrnyFQ(a)mail.gmail.com>
<CAF0zDV60iZZQFnbuPwCUzSGnvFY8xn1pCtq46d982xYvU_UaUw(a)mail.gmail.com>
<CAMRbyysJLOtWKXFX93zyyEcrDFaq+S=7x9Ek4GT3VXr-+zcjug(a)mail.gmail.com>
<CAF0zDV4RsA5ux3KOW2Tg+ZGWXR_3fhpVfWLKsnF1oryZ0F=PbQ(a)mail.gmail.com>
In-Reply-To: <CAF0zDV4RsA5ux3KOW2Tg+ZGWXR_3fhpVfWLKsnF1oryZ0F=PbQ(a)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--
2709
days inactive
2878
days old
23 comments
14 participants
participants (14)
-
Andrea Ghelardi -
Barak Korren -
Daniel Erez -
Edward Haas -
Jakub Niedermertl -
Maor Lipchuk -
Marc Dequènes (Duck) -
Martin Polednik -
Martin Sivak -
Michal Skrivanek -
Nir Soffer -
Roman Mohr -
Roy Golan -
Yaniv Kaul