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<