Migrate website documentation to the Wiki

[Jonathan Ernst]

Hi everyone,

I'm willing to move every simple textual (static content) page from the
website to the Wiki and link from the website to the corresponding
pages.

The advantages are obvious:
- makes it easy to keep these pages up-to-date
- makes it easy for non-dev. contributors to keep these pages up-to-date

The problems are:
- when clicking on a link from winehq to the wiki the left menu will
change which can be confusing

I notice that this has already been made for the janitorial page.

The pages I'd like to move are about:
http://cvs.winehq.org/cvsweb/lostwages/templates/en/*

What do you think ?

[Jeremy White]

> I'm willing to move every simple textual (static content) page from the
> website to the Wiki and link from the website to the corresponding
> pages.

I think this is a bad idea.

The current system ensures that changes to the core parts
of WineHQ are reviewed before being made, whereas a Wiki
can allow things to change willy-nilly, often reflecting
the views of the last person to touch a page, rather
than a consensus.

For things that are relatively fluid, like statii and such,
I think the Wiki makes great sense.  But for things that
are, essentially, static, I think the current static
web site works fine.

Cheers,

Jeremy

[Brian Vincent]

On 10/3/05, Jeremy White  wrote:
> > I'm willing to move every simple textual (static content) page from the
> > website to the Wiki and link from the website to the corresponding
> > pages.

I'll agree for the same reasons Jeremy cited.  The static pages are
relatively static and one of the only exceptions to that was a
Janitorial page which really required a quick way to jot down ideas. 
There are two pages that might be useful to move though: Fun Projects
and Resources.

-Brian

[Dimi Paun]

From: "Brian Vincent"
> I'll agree for the same reasons Jeremy cited.  The static pages are
> relatively static and one of the only exceptions to that was a
> Janitorial page which really required a quick way to jot down ideas. 
> There are two pages that might be useful to move though: Fun Projects
> and Resources.

ACK. I also don't think the Wiki is the right medium for the stuff 
on the site. We should however move the Fun Projects and TODO page
over. I've started on the TODO, but I still have a bit to finish
it off.

[Molle Bestefich]

Jeremy White wrote:
> > I'm willing to move every simple textual (static content) page from the
> > website to the Wiki and link from the website to the corresponding
> > pages.
>
> I think this is a bad idea.
>
> The current system ensures that changes to the core parts
> of WineHQ are reviewed before being made, whereas a Wiki
> can allow things to change willy-nilly, often reflecting
> the views of the last person to touch a page, rather
> than a consensus.

OTOH, the current system seems to ensure that many parts of WineHQ are
very outdated.

Isn't there a compromise where Wiki's upfront editing capabilities can
be used to ensure up-to-date, dynamic content while you also make sure
that nobody wrecks the pages?

I'm no wiki expert, but it seems like an obvious solution to have the
pages editable only by a certain class of users.  People wanting to
edit something could then just ask for edit access for certain pages
for correcting this or that on wine-devel and be granted those
privileges on a case-by-case basis.

Or is that simply impossible..

[James Hawkins]

On 10/3/05, Molle Bestefich  wrote:
> Isn't there a compromise where Wiki's upfront editing capabilities can
> be used to ensure up-to-date, dynamic content while you also make sure
> that nobody wrecks the pages?
>
> I'm no wiki expert, but it seems like an obvious solution to have the
> pages editable only by a certain class of users.  People wanting to
> edit something could then just ask for edit access for certain pages
> for correcting this or that on wine-devel and be granted those
> privileges on a case-by-case basis.
>
> Or is that simply impossible..

This method is already available in the form of checking out lostwages
cvs, making changes, doing a diff, and sending in the patch to be
accepted.  The only difference is that anyone can make changes to
lostwages this way (assuming they get committed).

--
James Hawkins

[Dan Kegel]

On 10/3/05, James Hawkins  wrote:
> This method is already available in the form of checking out lostwages
> cvs, making changes, doing a diff, and sending in the patch to be
> accepted.  The only difference is that anyone can make changes to
> lostwages this way (assuming they get committed).

There is a certain lack of feedback in the process, though.
I did exactly what you suggested:
http://www.winehq.org/pipermail/wine-patches/2005-September/021063.html
but haven't heard back, nor has the change been committed.

[Jonathan Ernst]

Le lundi 03 octobre 2005 à 13:23 -0700, Dan Kegel a écrit :
> On 10/3/05, James Hawkins  wrote:
> > This method is already available in the form of checking out lostwages
> > cvs, making changes, doing a diff, and sending in the patch to be
> > accepted.  The only difference is that anyone can make changes to
> > lostwages this way (assuming they get committed).
>
> There is a certain lack of feedback in the process, though.
> I did exactly what you suggested:
> http://www.winehq.org/pipermail/wine-patches/2005-September/021063.html
> but haven't heard back, nor has the change been committed.

I think it would be preferable to put these infos in the Wiki or in
lostwages and avoid having resources at too much different places, it
will just confuse users imho. I know you don't like Wikis, but it's just
a matter of copy pasting your content. I can do it if you want.

[Molle Bestefich]

James Hawkins wrote:
> Molle Bestefich wrote:
> > Isn't there a compromise where Wiki's upfront editing capabilities can
> > be used to ensure up-to-date, dynamic content while you also make sure
> > that nobody wrecks the pages?
> >
> > I'm no wiki expert, but it seems like an obvious solution to have the
> > pages editable only by a certain class of users.  People wanting to
> > edit something could then just ask for edit access for certain pages
> > for correcting this or that on wine-devel and be granted those
> > privileges on a case-by-case basis.
>
> This method is already available in the form of checking out lostwages
> cvs, making changes, doing a diff, and sending in the patch to be
> accepted.  The only difference is that anyone can make changes to
> lostwages this way (assuming they get committed).

Technically speaking, perhaps.

But a wiki lends itself to editing so much better than the tardy
process of finding the right CVS server, logging in, checking out a
working copy, finding the piece of documentation that is relevant,
making a change, checking if it compiles, sending a patch to
wine-patches (that never shows up) and to wine-devel (and never
receiving a response).

Compare that to just sending a mail to wine-devel saying eg. "hey
guys, there's two <A> links with 'binary' in their name on the
download page, one of them should be 'third-party', can I get editing
rights to it?

In the concrete case of the download page the answer would probably be
"No, but we'll go fix it for you", but you get the drift.  Ahem.

For any other page the response will probably be "Sounds good, you've
got access to edit the <blah blah> section now.  Remember to click
<preview> and see if it looks good before you commit."

[Molle Bestefich]

Molle Bestefich wrote:
> > This method is already available in the form of checking out lostwages
> > cvs, making changes, doing a diff, and sending in the patch to be
> > accepted.  The only difference is that anyone can make changes to
> > lostwages this way (assuming they get committed).
>
> But a wiki lends itself to editing so much better than the tardy
> process of finding the right CVS server, logging in, checking out a
> working copy, finding the piece of documentation that is relevant,
> making a change, checking if it compiles, sending a patch to
> wine-patches (that never shows up) and to wine-devel (and never
> receiving a response).
> Compare that to just sending a mail to wine-devel saying eg. "hey
> guys, there's [snip], can I get editing rights to it?
>
> [snip] the response will probably be "Sounds good, you've
> got access to edit the <blah blah> section now.  Remember to click
> <preview> and see if it looks good before you commit."

I generally think that the upfront editing capabilities is a very good
trade-in for the pre-commit peer review that we get with the CVS
solution.

But I'll agree that before anyone makes their initial contribution,
there should be some peer review.

So how about this:
Use one of the Wikis that has a CVS (or SVN, for that matter) backend.
New contributors will have to checkout a WC, conjure up a patch and
send it to wine-devel.
Others can judge the quality of their contribution, and if it seems
like the contributor actually posseses sane judgement when it comes to
document(ation) editing, they can be given Wiki edit privileges.

Hum?
Just a suggestion.

[Jeremy Newman]

Also, don't forget. The WineHQ docs are in SGML which provides tools to
convert it to any format. (html, PS, PDF, etc.) We really don't want to
give up on those abilities.

For any page that isn't SGML, sure it could be converted into a Wiki. In
fact, I'm now considering moving the entire WineHQ site to the wiki. You
all have been doing a bang up job keeping the Wiki updated. So far
proving me wrong that all Wiki's are junkyards of useless outdated
information. The only problem would be the WWN issues.

On Mon, 2005-10-03 at 07:17 -0500, Jeremy White wrote:
> > I'm willing to move every simple textual (static content) page from the
> > website to the Wiki and link from the website to the corresponding
> > pages.
>
> I think this is a bad idea.
>
> The current system ensures that changes to the core parts
> of WineHQ are reviewed before being made, whereas a Wiki
> can allow things to change willy-nilly, often reflecting
> the views of the last person to touch a page, rather
> than a consensus.
>
> For things that are relatively fluid, like statii and such,
> I think the Wiki makes great sense.  But for things that
> are, essentially, static, I think the current static
> web site works fine.
>
> Cheers,
>
> Jeremy

[Molle Bestefich]

Jeremy Newman wrote:
> Also, don't forget. The WineHQ docs are in SGML which provides tools to
> convert it to any format. (html, PS, PDF, etc.) We really don't want to
> give up on those abilities.

Right.
Hmm, let's see.  Counting the number of items currently in use in the
SGML docs, there's:
 * Paragraphs
 * Headlines
 * Bulleted lists
 * Numbered lists
 * Cross references to other doc pages
 * Links to pages outside WineHQ

And probably a couple others.
Any Wiki has those too, just in a different (also ASCII-based) syntax.

I hereby volunteer to write a parser that eats MoinMoin (or whatever)
and spits out SGML to use in the conversion process.  Problem solved? 
I hope so, but please feel free to try and prove me wrong ;-).

Let me know what's desirable and I'll whip something up.
> In fact, I'm now considering moving the entire WineHQ site to the wiki.
> You all have been doing a bang up job keeping the Wiki updated.
> So far proving me wrong that all Wiki's are junkyards of useless
> outdated information.

lol :-D.
> The only problem would be the WWN issues.

If anyone has the time, here's a dumb newbie that'd love to be
enlightened..  Why?

[Jonathan Ernst]

Le mardi 04 octobre 2005 à 09:40 -0500, Jeremy Newman a écrit :
> Also, don't forget. The WineHQ docs are in SGML which provides tools to
> convert it to any format. (html, PS, PDF, etc.) We really don't want to
> give up on those abilities.
>
> For any page that isn't SGML, sure it could be converted into a Wiki. In
> fact, I'm now considering moving the entire WineHQ site to the wiki. You
> all have been doing a bang up job keeping the Wiki updated. So far
> proving me wrong that all Wiki's are junkyards of useless outdated
> information. The only problem would be the WWN issues.

That was exactly what I wanted to do:

- let the sgml, wwn, press releases and so on where they are
- move the rest to the wiki

Sorry if that was not clear enough in my first message (when I said
static I meant content that is not generated dynamically from some other
files which excludes sgml docs and wwn).

Regards !

[Jeremy Newman]

On Tue, 2005-10-04 at 17:10 +0200, Jonathan Ernst wrote:
> That was exactly what I wanted to do:
> - let the sgml, wwn, press releases and so on where they are
> - move the rest to the wiki
>
> Sorry if that was not clear enough in my first message (when I said
> static I meant content that is not generated dynamically from some other
> files which excludes sgml docs and wwn).

Ahh sounds good to me. Might be time to talk to Dimi about moving the
hosting of the Wiki over to the WineHQ.org box then.

I'm all for reducing my load. You don't even want to see my internal
CodeWeavers bug/todo list. Ish!

Just wanted to make my point that it would be crazy to loose all the
useful features that SGML provides. It's not hard to learn to use and
submit patches for the mainline SGML docs. The rest of the WineHQ
content is less than 20 pages to move over to the Wiki.

[Molle Bestefich]

Jeremy Newman wrote:
> Just wanted to make my point that it would be crazy to loose all the
> useful features that SGML provides.

Killer!...
MoinMoin 1.3.5 supports DocBook parsing and generation.

Any reason why that wouldn't be good enough?
> It's not hard to learn to use and submit
> patches for the mainline SGML docs.

Everything's relative, why not make it even easier.

[Jeremy Newman]

On Tue, 2005-10-04 at 15:26 +0000, Molle Bestefich wrote:
> Jeremy Newman wrote:
> > Just wanted to make my point that it would be crazy to loose all the
> > useful features that SGML provides.
>
> Killer!...
> MoinMoin 1.3.5 supports DocBook parsing and generation.
>
> Any reason why that wouldn't be good enough?

We need to weigh all the possibilities here. Jumping from our current
process is not something that will happen overnight. My first reaction
is "No way Dude". It might help if someone put together a proof of
concept here.

I'm sure there are features of our current SGML docs that I have
forgotten about. Multi-Languages for one maybe.

[Molle Bestefich]

Jeremy Newman wrote:
> > Killer!...
> > MoinMoin 1.3.5 supports DocBook parsing and generation.
> >
> > Any reason why that wouldn't be good enough?
>
> We need to weigh all the possibilities here. Jumping from our current
> process is not something that will happen overnight. My first reaction
> is "No way Dude". It might help if someone put together a proof of
> concept here.

Ok.
I'll consider doing that.  Until then I'll just stop my Wiki rant :-).
> I'm sure there are features of our current SGML docs that I have
> forgotten about. Multi-Languages for one maybe.

Hmm.  Multi language Wiki's do exist.  It's probably going to be a
question whether exactly The Right Wiki (tm) can be found that fits in
everywhere.

http://doc-book.sourceforge.net/homepage/
Oops!  Just one more rant.  Forgive me!
It seems to be a Wiki that will let you edit DocBook stuff online and
save your edits in CVS.

[Molle Bestefich]

Jeremy Newman wrote:
> Molle Bestefich wrote:
> > Jeremy Newman wrote:
> > > Just wanted to make my point that it would be crazy to loose all the
> > > useful features that SGML provides.
> >
> > MoinMoin 1.3.5 supports DocBook parsing and generation.

And if that's not good enough, there's another solution:
Store the docs in XML, only convert them to SGML as part of the
process of converting them to {PS,PDF,HTML}.

Hope I'm not stepping on anyone's toes, but in practical terms, that's
probably the best way to use SGML today, given all the XML tools that
exist?
> Jumping from our current process is not something that will happen overnight.

My believe is that if you show the attitude that you really want to do
the Best Thing, and if you can provide a way for the process to take
action in bite-size pieces of work, there'll be plenty of volunteers
standing ready to do the actual work.  Hope I'm not coming off
provocative.
> We need to weigh all the possibilities here.
> My first reaction is "No way Dude".

Ok.  I stumbled upon a quite interesting posting by Jay Levitt that
I'd like to direct your attention at:
http://article.gmane.org/gmane.comp.version-control.subversion.devel/68571/

I'll quote teasers:
"you shouldn't try to think of a wiki as just a webby way to edit and
commit doc patches."

..."a wiki engine that flags any given version of the page as
'reviewed'; if the last editor was not on the commit list, it could
say 'This page has not yet been formally reviewed.  Click *here* for
the last approved revision.'"

But please read the entire posting as it says much more that seems
very appropriate to this discussion.

(Skip the first quote + paragraph though ;-).)

(The original posting in that thread is here:
http://article.gmane.org/gmane.comp.version-control.subversion.devel/68402/
and may or may not be needed as context.)

[Chris Morgan]

If we are going to consider moving the wiki can we move to wiki
software that lets you use html in wiki entries?  I'd imagine not
having to learn wiki tags would make it easier for people to produce
well formatted pages.

Chris

On 10/4/05, Jeremy Newman  wrote:
> On Tue, 2005-10-04 at 17:10 +0200, Jonathan Ernst wrote:
> > That was exactly what I wanted to do:
> > - let the sgml, wwn, press releases and so on where they are
> > - move the rest to the wiki
> >
> > Sorry if that was not clear enough in my first message (when I said
> > static I meant content that is not generated dynamically from some other
> > files which excludes sgml docs and wwn).
>
> Ahh sounds good to me. Might be time to talk to Dimi about moving the
> hosting of the Wiki over to the WineHQ.org box then.
>
> I'm all for reducing my load. You don't even want to see my internal
> CodeWeavers bug/todo list. Ish!
>
> Just wanted to make my point that it would be crazy to loose all the
> useful features that SGML provides. It's not hard to learn to use and
> submit patches for the mainline SGML docs. The rest of the WineHQ
> content is less than 20 pages to move over to the Wiki.

[Dan Kegel]

On 10/3/05, Jonathan Ernst  wrote:
> I'm willing to move every simple textual (static content) page from the
> website to the Wiki

Please don't do this.

[Jonathan Ernst]

Le lundi 03 octobre 2005 à 09:25 -0700, Dan Kegel a écrit :
> On 10/3/05, Jonathan Ernst  wrote:
> > I'm willing to move every simple textual (static content) page from the
> > website to the Wiki
>
> Please don't do this.

I won't as nobody wants it. Let's just hope that the documentation will
be a little bit less outdated. In the meanwhile I sent 5 or 6 patches to
update some parts of lostwages that were out of date.