On Tue, Jun 20, 2017 at 10:22 PM, Nir Soffer <nsof...@redhat.com> wrote:
> > בתאריך יום ג׳, 20 ביוני 2017, 13:10, מאת Martin Sivak <msi...@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 <eh...@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.skriva...@redhat.com> wrote: >> >> >> >> >> >> On 16 Jan 2017, at 11:13, Roy Golan <rgo...@redhat.com> wrote: >> >> >> >> >> >> >> >> On 11 January 2017 at 17:06, Marc Dequènes (Duck) <d...@redhat.com> >> wrote: >> >>> >> >>> Quack, >> >>> >> >>> On 01/08/2017 06:39 PM, Barak Korren wrote: >> >>> > On 8 January 2017 at 10:17, Roy Golan <rgo...@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 >> >> de...@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 >> de...@ovirt.org >> http://lists.ovirt.org/mailman/listinfo/devel > >
_______________________________________________ Users mailing list Users@ovirt.org http://lists.ovirt.org/mailman/listinfo/users