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