Re: [ovirt-users] [ovirt-devel] 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@redhat.com> wrote:
On Wed, Jan 4, 2017 at 11:41 AM, Roy Golan <rgolan@redhat.com> wrote:
On 4 January 2017 at 12:17, Maor Lipchuk <mlipchuk@redhat.com> wrote:
On Wed, Jan 4, 2017 at 11:38 AM, Daniel Erez <derez@redhat.com> wrote:
On Wed, Jan 4, 2017 at 9:57 AM, Roy Golan <rgolan@redhat.com> wrote:
I'm getting the feeling I'm not alone in this, authoring and
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
publishing 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@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
On 8 January 2017 at 10:17, Roy Golan <rgolan@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@redhat.com RHCE, RHCi, RHV-DevOps Team https://ifireball.wordpress.com/
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@redhat.com> To: Barak Korren <bkorren@redhat.com>, Roy Golan <rgolan@redhat.com> Cc: devel <devel@ovirt.org>, users <users@ovirt.org>, infra <infra@ovirt.org> Message-ID: <6e6f7b97-9d8d-1759-5dab-c64bba86de35@redhat.com> Subject: Re: [ovirt-devel] [ovirt-users] Lowering the bar for wiki contribution? References: <CAC_JqcnVfGeFm+xQmZU-QEbp57efphO3jhPw5rDqux7d0DCu9A@mail.gmail.com> <CAP84NrtLshq30DJPmJ6==p2DThWokKqBetKpmhKFp+r-E2CVpw@mail.gmail.com> <CAJ1JNOcxk-=Aodrc0gM7hdJi-N0nyn+vwTkbjyTEKMZNGZXZ3A@mail.gmail.com> <CAC_Jqcnkqo3sGyBqc61zo7qN61ua0ZM1f1oTPkXHcH=L2_-HQg@mail.gmail.com> <CAJVw3Ezs9bSn=OLyLRfkz=twJNn1LuzdAjbV0qTyvAcVS+KF2w@mail.gmail.com> <CAC_Jqcku_hmpF25n4Ekrdsq4SzXRWsc0jGxbSeOyao3Snie4WQ@mail.gmail.com> <CAGJrMmqKJAycawV91RDxGF5ERB3snt6s9PNtfjCPmsRO4619qA@mail.gmail.com> In-Reply-To: <CAGJrMmqKJAycawV91RDxGF5ERB3snt6s9PNtfjCPmsRO4619qA@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@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--
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck@redhat.com> wrote:
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
On 8 January 2017 at 10:17, Roy Golan <rgolan@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.
On 16 Jan 2017, at 11:13, Roy Golan <rgolan@redhat.com> wrote: =20 =20 =20 On 11 January 2017 at 17:06, Marc Dequ=C3=A8nes (Duck) = <duck@redhat.com <mailto:duck@redhat.com>> wrote: Quack, =20 On 01/08/2017 06:39 PM, Barak Korren 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
On 8 January 2017 at 10:17, Roy Golan <rgolan@redhat.com = <mailto:rgolan@redhat.com>> wrote: procedures one. =20 I do thin it is. We are involved in the tooling, for their =
--Apple-Mail=_9F416020-C8F4-48D9-A648-B6277A20911E Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 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.
=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 =
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 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
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
=20 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.
=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 =
it was also a bit difficult to edit, plus a barrier of ~1 month it took = to get an account 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@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@redhat.com</a>> = 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@redhat.com</a>></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@redhat.com</a>> = 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@ovirt.org</a><br = class=3D"">http://lists.ovirt.org/mailman/listinfo/devel</div></blockquote=
</div><br class=3D""></body></html>=
--Apple-Mail=_9F416020-C8F4-48D9-A648-B6277A20911E--
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@redhat.com> wrote:
On 16 Jan 2017, at 11:13, Roy Golan <rgolan@redhat.com> wrote:
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck@redhat.com> wrote:
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
On 8 January 2017 at 10:17, Roy Golan <rgolan@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@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
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@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@redhat.com> wrote:
On 16 Jan 2017, at 11:13, Roy Golan <rgolan@redhat.com> wrote:
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck@redhat.com> wrote:
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
On 8 January 2017 at 10:17, Roy Golan <rgolan@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@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak <msivak@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@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@redhat.com> wrote:
On 16 Jan 2017, at 11:13, Roy Golan <rgolan@redhat.com> wrote:
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck@redhat.com>
wrote:
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
On 8 January 2017 at 10:17, Roy Golan <rgolan@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@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Devel mailing list Devel@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
On Tue, Jun 20, 2017 at 10:22 PM, Nir Soffer <nsoffer@redhat.com> wrote:
בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak <msivak@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
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
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@redhat.com> wrote:
On 16 Jan 2017, at 11:13, Roy Golan <rgolan@redhat.com> wrote:
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck@redhat.com>
wrote:
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
On 8 January 2017 at 10:17, Roy Golan <rgolan@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
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
On Thu, Jun 15, 2017 at 8:11 PM, Edward Haas <ehaas@redhat.com> wrote: that for maintenance, 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@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Devel mailing list Devel@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
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@redhat.com> wrote:
בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak <msivak@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@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@redhat.com> wrote:
On 16 Jan 2017, at 11:13, Roy Golan <rgolan@redhat.com> wrote:
On 11 January 2017 at 17:06, Marc Dequènes (Duck) <duck@redhat.com> wrote:
Quack,
On 01/08/2017 06:39 PM, Barak Korren wrote:
On 8 January 2017 at 10:17, Roy Golan <rgolan@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@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users
_______________________________________________ Devel mailing list Devel@ovirt.org http://lists.ovirt.org/mailman/listinfo/devel
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@redhat.com> To: Martin Sivak <msivak@redhat.com>, Nir Soffer <nsoffer@redhat.com> Cc: Edward Haas <edwardh@redhat.com>, devel <devel@ovirt.org>, infra <infra@ovirt.org>, users <users@ovirt.org> Message-ID: <24cf31c6-0b1e-cf4c-6843-d44f63b5d4e4@redhat.com> Subject: Re: [ovirt-devel] [ovirt-users] Lowering the bar for wiki contribution? References: <CAC_JqcnVfGeFm+xQmZU-QEbp57efphO3jhPw5rDqux7d0DCu9A@mail.gmail.com> <CAP84NrtLshq30DJPmJ6==p2DThWokKqBetKpmhKFp+r-E2CVpw@mail.gmail.com> <CAJ1JNOcxk-=Aodrc0gM7hdJi-N0nyn+vwTkbjyTEKMZNGZXZ3A@mail.gmail.com> <CAC_Jqcnkqo3sGyBqc61zo7qN61ua0ZM1f1oTPkXHcH=L2_-HQg@mail.gmail.com> <CAJVw3Ezs9bSn=OLyLRfkz=twJNn1LuzdAjbV0qTyvAcVS+KF2w@mail.gmail.com> <CAC_Jqcku_hmpF25n4Ekrdsq4SzXRWsc0jGxbSeOyao3Snie4WQ@mail.gmail.com> <CAGJrMmqKJAycawV91RDxGF5ERB3snt6s9PNtfjCPmsRO4619qA@mail.gmail.com> <6e6f7b97-9d8d-1759-5dab-c64bba86de35@redhat.com> <CAC_Jqcn6-OUKKDz2B=SF_aqwys9qrSQ+Zdhi5H8=8F_4De5Egg@mail.gmail.com> <F6E943F2-E8A2-43A1-8EF0-F08EEC60A2D5@redhat.com> <CALmkdFQM4XgtQ+opmBD9WiRQhv1puoOEj_Vn9dfS9OeSqrnyFQ@mail.gmail.com> <CAF0zDV60iZZQFnbuPwCUzSGnvFY8xn1pCtq46d982xYvU_UaUw@mail.gmail.com> <CAMRbyysJLOtWKXFX93zyyEcrDFaq+S=7x9Ek4GT3VXr-+zcjug@mail.gmail.com> <CAF0zDV4RsA5ux3KOW2Tg+ZGWXR_3fhpVfWLKsnF1oryZ0F=PbQ@mail.gmail.com> In-Reply-To: <CAF0zDV4RsA5ux3KOW2Tg+ZGWXR_3fhpVfWLKsnF1oryZ0F=PbQ@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--
participants (7)
-
Barak Korren -
Edward Haas -
Marc Dequènes (Duck) -
Martin Sivak -
Michal Skrivanek -
Nir Soffer -
Roy Golan