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