Migrate website documentation to the Wiki
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 ?
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
On 10/3/05, Jeremy White <jwhite(a)codeweavers.com> 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
From: "Brian Vincent" <brian.vincent(a)gmail.com>
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. -- Dimi Paun <dimi(a)lattica.com> Lattica, Inc.
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..
On 10/3/05, Molle Bestefich <molle.bestefich(a)gmail.com> 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
On 10/3/05, James Hawkins <truiken(a)gmail.com> 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.
Le lundi 03 octobre 2005 à 13:23 -0700, Dan Kegel a écrit :
On 10/3/05, James Hawkins <truiken(a)gmail.com> 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. -- Jonathan Ernst <Jonathan(a)ErnstFamily.ch>
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 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.
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
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?
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 !
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.
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.
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.
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.
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.)
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 <jnewman(a)codeweavers.com> 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.
Le lundi 03 octobre 2005 à 09:25 -0700, Dan Kegel a écrit :
On 10/3/05, Jonathan Ernst <Jonathan(a)ernstfamily.ch> 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. -- Jonathan Ernst <Jonathan(a)ErnstFamily.ch>
participants (9)
-
Brian Vincent -
Chris Morgan -
Dan Kegel -
Dimi Paun -
James Hawkins -
Jeremy Newman -
Jeremy White -
Jonathan Ernst -
Molle Bestefich