[Qemu-devel] [RFC] wiki.qemu.org

[Qemu-devel] [RFC] wiki.qemu.org

[Anthony Liguori]

Hi,

I've been (slowly) working to convert qemu.org to a wiki in order to 
allow more community participation in the website.  I've finally got a 
site setup and to my liking with all of the www.qemu.org content migrated.

Before doing the switch, I need to figure out what to do with the 
current texi documentation.  I think it makes sense to move 
qemu-doc.texi to a wiki page and remove it from the source repository.  
The other option would be to link to it as an external page and keep it 
within revision control.

Does anyone have strong opinions one way or another?

BTW: you can take a look at the current content at 
http://wiki.qemu.org.  Once we decide what to do with the texi 
documentation, it will be reachable via http://www.qemu.org/

Regards,

Anthony Liguori

Re: [Qemu-devel] [RFC] wiki.qemu.org

[Scott Tsai]

On Sat, Jan 30, 2010 at 3:44 AM, Anthony Liguori <anthony@codemonkey.ws> wrote:
> Hi,
>
> I've been (slowly) working to convert qemu.org to a wiki in order to allow
> more community participation in the website.  I've finally got a site setup
> and to my liking with all of the www.qemu.org content migrated.
>
> Before doing the switch, I need to figure out what to do with the current
> texi documentation.  I think it makes sense to move qemu-doc.texi to a wiki
> page and remove it from the source repository.  The other option would be to
> link to it as an external page and keep it within revision control.
>
> Does anyone have strong opinions one way or another?

To keep the code and documentation in sync, I suggest keeping the
portion generated from
qemu-img-cmds.hx, qemu-monitor.hx and qemu-options.hx in texinfo
format under revision control.
This encourages updating the documentation in the same patch that adds
new options and monitor commands.

The "QEMU System emulator for non PC targets" section in qemu-doc.texi
seems rather qemu version dependent as well? If true, moving this
information to a wiki risks the documentation not matching the qemu
version installed on users' machines.

Re: [Qemu-devel] [RFC] wiki.qemu.org

[Andreas Färber]

Hi,

Am 29.01.2010 um 20:44 schrieb Anthony Liguori:

> I need to figure out what to do with the current texi  
> documentation.  I think it makes sense to move qemu-doc.texi to a  
> wiki page and remove it from the source repository.  The other  
> option would be to link to it as an external page and keep it within  
> revision control.

The latter allows to have a stable version on the website and a  
development version inside the repository.
Otherwise we would either document unavailable options or, if we  
don't, probably forget adding Wiki documentation after a release.
Also, would you want to ship a snapshot of the Wiki page with the  
source tarballs?

The Wiki looks more pretty though. :)

Regards,
Andreas

Re: [Qemu-devel] [RFC] wiki.qemu.org

[Anthony Liguori]

On 01/29/2010 02:29 PM, Andreas Färber wrote:
> Hi,
>
> Am 29.01.2010 um 20:44 schrieb Anthony Liguori:
>
>> I need to figure out what to do with the current texi documentation.  
>> I think it makes sense to move qemu-doc.texi to a wiki page and 
>> remove it from the source repository.  The other option would be to 
>> link to it as an external page and keep it within revision control.
>
> The latter allows to have a stable version on the website and a 
> development version inside the repository.
> Otherwise we would either document unavailable options or, if we 
> don't, probably forget adding Wiki documentation after a release.
> Also, would you want to ship a snapshot of the Wiki page with the 
> source tarballs?

If we have documentation on the website, I think it may be appropriate 
to just include a man page in the source tarball and leave all of the 
other documentation on the website.

I think our user manual is currently a bit difficult to read through and 
is certainly out of date in a lot of places.  My expectation is that 
putting it on the wiki would result in it becoming quite a bit more 
readable and quite a bit more up-to-date.

> The Wiki looks more pretty though. :)

Yeah, I like it too.  The theme is the same as what's used on 
wiki.mozilla.org.

Regards,

Anthony Liguori

> Regards,
> Andreas

Re: [Qemu-devel] [RFC] wiki.qemu.org

[Stefan Weil]

Anthony Liguori schrieb:
> Hi,
>
> I've been (slowly) working to convert qemu.org to a wiki in order to
> allow more community participation in the website.  I've finally got a
> site setup and to my liking with all of the www.qemu.org content
> migrated.
>
> Before doing the switch, I need to figure out what to do with the
> current texi documentation.  I think it makes sense to move
> qemu-doc.texi to a wiki page and remove it from the source
> repository.  The other option would be to link to it as an external
> page and keep it within revision control.
>
> Does anyone have strong opinions one way or another?
>
> BTW: you can take a look at the current content at
> http://wiki.qemu.org.  Once we decide what to do with the texi
> documentation, it will be reachable via http://www.qemu.org/
>
> Regards,
>
> Anthony Liguori
>
>
>

Hi,

it's great to have an "official" QEMU wiki.
What will happen with http://qemu.kidsquid.com/?

Before removing the texi documents, there should
be solutions for these topics:

* How do we get a man page for a certain qemu release?

* How do we get online documentation for a certain qemu release?

* How do we get offline documentation (html without internet access)?

* How do we get printed documentation which looks nice?

The wiki provides online documentation. It can do this for
several qemu releases, too. But maintainance of serveral
pages which are nearly identical will be difficult.
Applying documentation patches to qemu releases is easier.

For man pages, offline or printed documentation (needed for
distributions), the texi documents work well. I see no
easy way to replace them.

Therefore I'd keep the texi documentation.

Instead of adding an external link to the wiki,
it should be possible to create mediawiki output
from texi. This output could be copied to the
qemu wiki using copy+paste, or maybe it is also
possible to create mediawiki pages automatically
on demand.

Regards,
Stefan Weil

Re: [Qemu-devel] [RFC] wiki.qemu.org

[Anthony Liguori]

On 01/29/2010 03:47 PM, Stefan Weil wrote:
> Hi,
>
> it's great to have an "official" QEMU wiki.
> What will happen with http://qemu.kidsquid.com/?
>    

I don't know.  It's certainly provided a great service over the years.  
I see no reason not to continue to link to it and if people want to move 
content in either direction, that would be okay to.

> Before removing the texi documents, there should
> be solutions for these topics:
>
> * How do we get a man page for a certain qemu release?
>
> * How do we get online documentation for a certain qemu release?
>
> * How do we get offline documentation (html without internet access)?
>
> * How do we get printed documentation which looks nice?
>    

All good points.  Personally, I think there are two types of 
documentation.  There is exhaustive option documentation which covers 
things like the monitor commands and the command line options.  This 
documentation should continue to live in the git tree IMHO and we should 
continue to generate man pages and online help from this source.

Then I think there is user documentation.  This is documentation that is 
more oriented to guide a user through what they should and shouldn't do 
and most importantly, how to solve problems on their own.  This think 
this later category is where a wiki shines.

I think qemu-img-cmds.hx, qemu-monitor.hx, and qemu-options.hx 
definitely fall into the first category.  I think qemu-doc.texi and 
qemu-tech.texi fall into the second category.  I think the remaining 
texi files live in both worlds.

> The wiki provides online documentation. It can do this for
> several qemu releases, too. But maintainance of serveral
> pages which are nearly identical will be difficult.
> Applying documentation patches to qemu releases is easier.
>
> For man pages, offline or printed documentation (needed for
> distributions), the texi documents work well. I see no
> easy way to replace them.
>
> Therefore I'd keep the texi documentation.
>
> Instead of adding an external link to the wiki,
> it should be possible to create mediawiki output
> from texi. This output could be copied to the
> qemu wiki using copy+paste, or maybe it is also
> possible to create mediawiki pages automatically
> on demand.
>    

That's an interesting thought although it probably requires translating 
texi into a more friendly intermediary first.

Regards,

Anthony Liguori

Re: [Qemu-devel] [RFC] wiki.qemu.org

[Paul Brook]

> Before doing the switch, I need to figure out what to do with the
> current texi documentation.  I think it makes sense to move
> qemu-doc.texi to a wiki page and remove it from the source repository.
> The other option would be to link to it as an external page and keep it
> within revision control.

I think removing the official documentation to the wiki would be a bad idea.
Anyone shipping qemu needs documentation that matches the version they're 
actually shipping.  In particular I'd expect significant discrepancies between 
master and the various stable branches, so we need versioned documentation. A 
Wiki seems a poor solution to this.  It's also very useful to be able to ship 
html/pdf versions of the documentation for offline use. I'm not sure how 
feasible this is with wiki based documentation.

I'm happy for things like FAQs, howtos, internals documentation, explanation 
of design choices, etc. to be on the wiki.

Paul