בתאריך יום ג׳, 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