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